best practices for dev+testFeb 21
9a. 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.)
Show threadMarijke LuttekesFeb 21

@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.

Show threadPatrick Gerken
@mahryekuh @voidbot The outdated documentation argument I would counter with the Open-closed principle, at least for doc strings.
Also, outdated docs are a smell of bad code review practices.
Feb 21 at 1:56pmMona for iPhone
Show threadMarijke LuttekesFeb 21
@do3cc @voidbot What do you mean with open-closed principle?
Show threadPatrick GerkenFeb 21
@mahryekuh @voidbot I have memorized the short summary that code should be open for extention but closed for modification and before I wanted to answer, I looked up Wikipedia to find out that the definition has been fluid. I learned it in context of the Polymorphic explanation from Wikipedia. (1/2)
Show threadPatrick GerkenFeb 21
Roughly, you should not modify the methods of a class itself, but instead use other means like subclassing, if you want to extend functionality. In context of docstrings, if you need to update context and constraints documentation in the docstring, modifying the function or method may be a bad idea in itself. (2/2)
Show threadMarijke LuttekesFeb 21

@do3cc That is an interesting approach! I didn’t know it had a name.

I can see pros and cons to this approach, but I’m not against it.

Show threadClark Breyman (he/him)Feb 21

@do3cc - I remember working in a codebase that interpreted this as using inheritance for version control, with all prior versions still the the artifact. Lots of copy paste to fix method bugs.

It was murder to work in. 100% do not support. There are valid reasons to changing an existing implementation.

Show threadPatrick GerkenFeb 21
@clark It’s not a religion and breaking the principle can be the right choice. Like if I were to add Hyneks structlog to my code base, I would want to modify lots of methods adding a logger as an argument to my functions and methods, clearly violating that principle. But wrapping everything because I blindly follow the principle would make it a moot point to add structlog.
Having a common understanding and a name makes a discussion much simpler.