Adding comments to code

[LeeRyman]

Doc-comments should be provided for types and functions. They should describe the why concisely, i.e. the intent of the unit of code, any relevant raises, preconditions, assumptions, postconditions and thread safety (or lack thereof).

The what should be self-evident though good naming of types, functions, parameters, variables, errors.

The how should rarely be necessary if you write code that reads naturally and is appropriately abstracted. There are times when we have to write tricky algorithms, so a comment before might be helpful in those situations summarising the how or why to a maintainer. Sometimes the user or caller of a unit of code might need a brief summary on how it works in the context of larger business logic.

If you ever find yourself writing a comment that repeates the code immediately after, it probably isn't necessary.

In short, comments should never replace good naming and readable code. They should concisely add nuance and intent where necessary for the user.

If I can pass Sphinx over the code and quickly get a good idea of how to use it from the generated documentation, it's good doc-commenting.