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

Feb 21 at 1:03pmWeb
Show threadPatrick GerkenFeb 21
@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.
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.
Show threadMarijke LuttekesFeb 21

@voidbot Personal anecdote:

I also have a pet peeve specifically with the movement that abolishes docstrings nearly completely.

Not only do I know they are wrong based on the fact that their extremist stance has been disproven before, but also because the ones I met IRL were obnoxious about it.

https://hachyderm.io/@mahryekuh/116007381028407112

Marijke Luttekes (@[email protected])

@[email protected] I recently had to deal with a senior who has a near-religious opposition to code comments, to the point where he would delete them from my pull requests. To say it was frustrating is an understatement.

Hachyderm.io
Show threadakahnFeb 21
@mahryekuh @voidbot I worked with zealots who would actually REMOVE existing code comments 😭
Show threadMarijke LuttekesFeb 21

@akahn @voidbot Yep. Been there, done that.

In case of juniors: Because they had no clue yet, overestimating their own abilities, or because of misapplied laziness.

In case of seniors: Partially it was their religious resistance against comments, ot because [it seems like] they hated others doing work differently from them, or to improve their bus factor and seniority within their project.

In all cases they were not as impressive as they presented themselves to be.

Show threadakahnFeb 21
@mahryekuh @voidbot in my case recently it was seniors, ostensible leaders in the engineering org. What galled me was the notion that this was simply accepted best practice, not what it actually was: an opinion.
Show threadMarijke LuttekesFeb 21

@akahn @voidbot Yep, that is so infuriating.

The one I refer to in this post was even (not by choice) part of a meeting where a team concluded that there should be *more* documentation.

But apparently, the guy mistakes the “Clean Code” book for the frigging Bible, and had such a bus factor that he could run the project as if he owned it.

https://hachyderm.io/@mahryekuh/116007381028407112

Marijke Luttekes (@[email protected])

@[email protected] I recently had to deal with a senior who has a near-religious opposition to code comments, to the point where he would delete them from my pull requests. To say it was frustrating is an understatement.

Hachyderm.io
Show threadGolden Bunny of Destiny 🕯Feb 21
@mahryekuh @voidbot People should not write code because it will become outdated 🙃
Show threadGolden Bunny of Destiny 🕯Feb 21
@mahryekuh @voidbot As a junior developer I once ripped out a section of undocumented code for day of the week determination and replaced with a simple table driven solution. Later I learned it was implementing Zeller’s Congruence. I would still replace an undocumented smart ass solution with a documented simple approach.
Show threadMilesFeb 21
@mahryekuh @voidbot I find Docstrings, JavaDoc, etc. super helpful in the IDE. Even with code I wrote!
Show threadFionaFeb 21
@mahryekuh @voidbot Yes. And docstrings and similar put the documentation where the code is, which minimizes the friction of updating it.

(In work contexts I've dealt with "put documentation into this separate wiki-ish system". Recipe for disaster. Anything too big for a docstring should at least live in the source repo.)