Writing Comments

Lecture Notes for CS 190
Winter 2018
John Ousterhout

Reading: Chapters 10, 11, 13 of book
Comments are still controversial (!)
- A significant fraction of all commercial code (50%?) is uncommented
- Excuses:
  - "This code is self-documenting"
  - "I don't have time to write comments"
  - "Comments get out of date and become misleading"
  - "The comments I have seen are worthless; why bother?"
Why are comments needed?
- Code alone can't represent cleanly all the information in the mind of the designer
- Even if information could be deduced from code, it might be time-consuming:
Comments should describe things that are not obvious from the code.
Mistake #1: comments duplicate code
Mistake #2: non-obvious info is not described
Comments should be at a different level of detail than code
- Lower level comments provide precision (especially for variables, arguments, return values):
  - Exactly what is this thing?
  - What are the units?
  - Boundary conditions
    - Does "end" refer to the last value, or the value after the last one?
    - Is a null value allowed? If so, what does it mean?
  - If memory is dynamically allocated, who is responsible for freeing it?
  - Invariants?
- Higher-level comments capture intuition:
  - Abstractions: a higher-level description of what the code is doing.
  - Rationale for the current design: why the code is this way.
  - How to choose the value of a configuration parameter.
Two kinds of documentation for classes and methods:
- Interface: what someone needs to know in order to use this class or method
- Implementation: how the method or class works internally to implement the advertised interface.
- Important to separate these: do not describe the implementation in the interface documentation!
Interface documentation:
- Put immediately before the class or method declaration
- Goal: describe the abstraction (create simple, intuitive model for users)
- Simpler is better
- Complete: must include everything that any user might need to know
- Interface description may use totally different terms than the implementation (if they are simpler)
Example: index range lookup
- Large table of objects in a storage system, split across dozens of servers
- Table has indexes for looking up objects by certain attributes (name, salary, etc.)
- IndexLookup class retrieves a range of values in index order
```
query = new IndexLookup(table, index, key1, key2);
while (true) {
    object = query.getNext();
    if (object == null) {
        break;
    }
    ...
}
```
Implementation documentation (comments inside methods):
- For many methods, not needed
- For longer methods, document major blocks of code
  - Describe what's happening at a higher level
  - E.g., what does each loop iteration do?
- Document tricky aspects, non-obvious reasons for code
- Document dependencies ("if you change this, you better also...")
- Documenting variables is less important for method local variables (can see all of the uses), but sometimes needed for longer methods or tricky variables.

Challenges with comments:
- It must be easy for people to find the right documentation at the right time
- The documentation must get updated as the code changes
Techniques:
- Document each thing exactly once: don't duplicate documentation (it won't get maintained)
  - Use references rather than repeating documentation: "See documentation for xyz method".
  - Don't duplicate interface documentation for overridden methods.
- Put documentation as close as possible to the relevant code
  - Next to variable and method declarations
  - Push in-method documentation down to the tightest enclosing context
- Don't say anything more in documentation than you need to
  - e.g., don't use comments in one place to describe design decisions elsewhere
  - Higher-level comments are less likely to become obsolete
- Look for "obvious" locations where people can easily find documentation (see Status example in slides)