We can agree on “not all situations”. Often the answer to “why did we do it this way?” is blazingly obvious, and no one wants a comment.
But we all know that sometimes the “why” isn’t obnoxious at all.
As far as I can tell, developers who do believe in self-documenting code either haven’t learned the power of “why?”, or they have a secret technique for encoding “why?” into their code structure.
If it’s the second thing, I would be delighted to be brought in on it. (No sarcasm. Maybe I’ve missed a trick here.)
If I am writing library code my why is you have an end use and I don’t care why you use it and you don’t care why I wrote it. You only care about what my code does so you can achieve your why.
If we are working on the same code we have different whys but the same what. Then your comment as to why isn’t the same as mine which makes the comment incorrect.
We are looking at a piece of code and you want to know how it works, because the stated what is wrong (bugs). This might be the “why” you are looking for, but I call this a “how”. This is the case where self documenting code is most important. Code should tell a second programmer how the code achieves the what without needing an additional set of verbose comments. The great thing about code is that it is literally the instructions on the how. The problem is conveying the how to other programmers.
There are three kinds of how: self evident, complex how’s requiring multiple levels of abstraction and lots of code and complex short how’s that are not apparent.
The third is where most people get into trouble. Almost all of these cases of complexity can be solved with only a single layer of abstraction and achieve easily readable self documenting code. The problem for many cases is that they start as a one off and people are lousy at putting in the work on a one-off solution. Sometimes the added work of abstraction, and building a performant abstraction, makes a small task a large one. In these cases comments can make sense.
Sometimes these short, complex how’s require specialists. Database queries, performant perl/functional queries, algorithmic operations, complex compile time optimized templates (or other language specific optimizations) and the like are some of the most common examples of these. This category of problem benefits most from a well defined interface with examples for use (which might be comments). The “how” of these are not as valuable for the average developer and often require specialist knowledge regardless of comments for understanding how they work. In these cases what they do is far more valuable than how or why.
You’ve given a lot of consideration to modern recently created code. But the best modern recent code goes on to become someone’s legacy nightmare. (The most fit and correct code survives long after anyone really wishes it would.)
In high quality legacy nightmare code “why” is lost, unless someone wrote it down.
I’ve been on both sides of that mystery. “Why didn’t they just do X?”
Sometimes it was because X didn’t exist yet, or wasn’t matute enough.
Sometimes it was because X is fundamentally the wrong solution, in a very subtle way.
There’s two ways to know the difference:
Painful trial and error.
A comment (or document) answering “why”.
I prefer the second way, but I happily charge more for the first way.
We can agree on “not all situations”. Often the answer to “why did we do it this way?” is blazingly obvious, and no one wants a comment.
But we all know that sometimes the “why” isn’t obnoxious at all.
As far as I can tell, developers who do believe in self-documenting code either haven’t learned the power of “why?”, or they have a secret technique for encoding “why?” into their code structure.
If it’s the second thing, I would be delighted to be brought in on it. (No sarcasm. Maybe I’ve missed a trick here.)
I’ll answer in a couple of different ways.
If I am writing library code my why is you have an end use and I don’t care why you use it and you don’t care why I wrote it. You only care about what my code does so you can achieve your why.
If we are working on the same code we have different whys but the same what. Then your comment as to why isn’t the same as mine which makes the comment incorrect.
We are looking at a piece of code and you want to know how it works, because the stated what is wrong (bugs). This might be the “why” you are looking for, but I call this a “how”. This is the case where self documenting code is most important. Code should tell a second programmer how the code achieves the what without needing an additional set of verbose comments. The great thing about code is that it is literally the instructions on the how. The problem is conveying the how to other programmers.
There are three kinds of how: self evident, complex how’s requiring multiple levels of abstraction and lots of code and complex short how’s that are not apparent.
The third is where most people get into trouble. Almost all of these cases of complexity can be solved with only a single layer of abstraction and achieve easily readable self documenting code. The problem for many cases is that they start as a one off and people are lousy at putting in the work on a one-off solution. Sometimes the added work of abstraction, and building a performant abstraction, makes a small task a large one. In these cases comments can make sense.
Sometimes these short, complex how’s require specialists. Database queries, performant perl/functional queries, algorithmic operations, complex compile time optimized templates (or other language specific optimizations) and the like are some of the most common examples of these. This category of problem benefits most from a well defined interface with examples for use (which might be comments). The “how” of these are not as valuable for the average developer and often require specialist knowledge regardless of comments for understanding how they work. In these cases what they do is far more valuable than how or why.
You’ve given a lot of consideration to modern recently created code. But the best modern recent code goes on to become someone’s legacy nightmare. (The most fit and correct code survives long after anyone really wishes it would.)
In high quality legacy nightmare code “why” is lost, unless someone wrote it down.
I’ve been on both sides of that mystery. “Why didn’t they just do X?”
There’s two ways to know the difference:
I prefer the second way, but I happily charge more for the first way.