Page Comparison

...

• Comments should describe the things that aren't obvious from the code. This implies two things:
  • Don't waste time writing comments for code that is already obvious, such as the following silly example:
        // Increment i.
    i++;
    A common mistake people make when writing comments is to use the same words in the comment that are already used in the code, and this reduces the value of the comment. For example, I recently saw the following comment in some RAMCloud code:
        // The epoch when this tablet was deleted.
    uint64_t epoch;
    The problem is, "the epoch" is already obvious from the code. What I need to know is "what is an epoch, and why is it needed?".
  • The comments should contain information that is not obvious from the code, such as why a particular variable is needed, or who is likely to call a particular method, or what are the units for variable. Comments are crucial for abstraction: abstractions will not be obvious from the code, so it's essential to describe them with comments (what is the common theme, or overall task for this class? what is the invariant for this variable? etc.).

...