Skip to content

Communal commenting

Communal commenting is a team based approach to writing clear, useful comments.

It may be a useful approach to take if you find yourself encountering no shit sherlock comments.

Background

When developers are writing code, they have their mind buried in many and deep levels of context for hours at a time. As a result, when we do this we are often in the worst position to understand what is and what isn't obvious to the code reader approaching without context.

Worse, the cognitive load of writing code is such that extraneous concerns usually have to be dispensed with - i.e. empathetically putting yourself in the shoes of the code reader and considering what additional context they would like to see.

This weight can be lifted by simply ignoring comments completely until there is a pull request and writing in comments which serve as answers to questions asked by reviewers.

Unlike the code writer, the reviewer will also usually be better able to have a holistic view of the code and understand both what is and isn't obvious.

The process

  1. Write code WITHOUT any comments and submit a pull request.
  2. Ask your team to review it and to comment wirh questions when they cannot easily discern what is going on or why.

  3. Turn the answers of the questions into:

  4. A docstring or comment in the code.

  5. A new glossary entry.
  6. More detailed explanation in a test executing the code.
  7. Documentation explaining background and the rationale behind decisions.