best practices for dev+test9a. Inevitably, code comments become lies over time. In practice, few people update comments when things change. Strive to make your code readable and self-documenting through good naming practices and known programming style. (This particular point about comments being lies is controversial, by the way. I still think it’s correct, and Kernighan and Pike, authors of The Practice of Programming, agree with me.)
Marijke Luttekes@voidbot Code needs to be self-descriptive, but code comments—docstrings in particular—are essential.
I have worked with anti-docstring people, and frankly, I've found that reality always proves them wrong in the end.
---
Good documentation does not describe the code in detail. Instead:
1. You have a single-line docstring that summarizes what the function does (unless the function name is blatantly obvious).
2. You have a longer section of documentation that describes caveats and philosophy, if needed. Preferably, you don't need this.
You need the summary (point 1) to reduce cognitive overload by avoiding the need to interpret code every time you look something up.
You need the author's notes (point 2) to provide context for special cases. These are facts that you cannot infer from the code itself.
---
Anything you do not write down will be forgotten.
The argument that people should not write documentation because it gets outdated annoys the hell out of me.
It is an arrogant way of disregarding part of one's due diligence as a programmer, the one where you ensure that code remains maintainable for years to come.
---
To summarize:
1. Documentation that compensates for poorly written code is bad.
2. Documentation as additional context to code is good.
akahn