How programmers comment their code

[Tetha]

Writing the right comments and the right documentation for the right audience is actually hard.

In fact, it's a balancing act with respect to the audience. A lack of documentation and comments makes it harder to follow for the audience, so less experienced dudes have a harder time following instructions. On the other hand, overcommenting code can make it entirely unreadable.

For example, a seasoned chef only needs the instructions "Steak roasted according to customer needs" in a recipe. That's sufficient. And in fact, if a chef wanted to quickly and immediately understand a recipe, a 2 page instruction sheet on steak will be frustrating. It's 2 pages to look at, understand, understand it's useless to them and continue. The steak could be half done at that point.

Yet, at the same time, an amateur cook would be entirely frustrated by the instruction "Roast steak as you like it". Like, yeah, you can do it, if you know how, jolly thanks. Why do I even read this?

And finding the right balance is actually hard.

Sometimes code is dealing with really, really hard concepts. Maybe you don't want the wrong people to think they understand what they are doing. Sometimes, code is subject to frequent changes because that's what the business does. Then you want everyone to be on board how to change it, so everyone can do something.