Although I do see your point, and I myself tend to "over comment" my own code, there is a valid argument to the code being self documented. Interestingly, with a "meta programming" language, such as our Hyperlambda, the code literally is self documented, due to the abilities of the programming language to extract meta data from the code, being able to intelligently understand what each snippet of code does, to the point where you can write stuff that's logically similar to the following (pseudo code).
Of course the above is pseudo code, but still a perfectly example of something easily achieved with a "meta programming language", resulting in that your "comments" literally becomes its code, and information about what the code does can be dynamically extracted using automated processes, allowing you to easily understand everything your code actually does, without having a single comment in your code base.
Still, kind of out of fear from possibly being wrong, I tend to document my code (too much) ... :/
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
"Why" is a question that has nothing to do with the implementation. It has something to do with the requirements. These come from the stake holders. They should document the requirements somewhere else, not in the code. If the code is the single source of truth for the requirements of your software, then you're doing something wrong.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
If it's really a matter of performance, then I agree. However, in today's web applications, performance on such a low level is almost never a concern. From what I've learnt, it almost always boils down to IO in a loop or other nested loops with cubic complexity.
Apart from that: readability > performance. Unless you're working in game industry or doing other low level stuff.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
I've spent a long-time in open source. The one thing that invariably remains…the source code (and it's git history). All other things rot and decay far faster.
So, include whatever comments can help provide contextual support of the local "state" of the code.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
In addition, one must consider that placing way finding comments in a code-base are of high value.
There have been a few cases, where past decisions/specs were lost but we still had code. I don't want to go and "backfill" those specs, so I'll write a note saying "This is my understanding given what I've been able to piece together."
Okay, maybe I am viewing it too much from a business perspective. It seems like there are a lot more specs from a non-technical view there. This somehow eliminates the need for specs inside code.
If you use comments as way to communicate with other developers working on the same code base and have no real communication channel outside of that, then I can better understand the necessity!
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
We're both looking at the same "elephant" but from different perspectives. The code is the most accurate representation of the product. It says exactly what the product is. There will invariably be cases where the intention of the code will be hidden in a private Slack channel, a lost email, or even an unrecorded Zoom meeting.
The code is the product and provides the most reliable place to "pin" a way finding comment/annotation.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
Although I do see your point, and I myself tend to "over comment" my own code, there is a valid argument to the code being self documented. Interestingly, with a "meta programming" language, such as our Hyperlambda, the code literally is self documented, due to the abilities of the programming language to extract meta data from the code, being able to intelligently understand what each snippet of code does, to the point where you can write stuff that's logically similar to the following (pseudo code).
Of course the above is pseudo code, but still a perfectly example of something easily achieved with a "meta programming language", resulting in that your "comments" literally becomes its code, and information about what the code does can be dynamically extracted using automated processes, allowing you to easily understand everything your code actually does, without having a single comment in your code base.
Still, kind of out of fear from possibly being wrong, I tend to document my code (too much) ... :/
I love self-documenting "What does the code do" but I have yet to see self-documenting "Why does it do it?"
Good point, but I was speaking of the ability to runtime extract semantic data about what the code does, not reading the code itself ...
But you've got a very good point ...
"Why" is a question that has nothing to do with the implementation. It has something to do with the requirements. These come from the stake holders. They should document the requirements somewhere else, not in the code. If the code is the single source of truth for the requirements of your software, then you're doing something wrong.
"Why did I choose to use this mapping method? Because in exploring the options this was the most performant."
That's never something you'll see in requirements somewhere and is ideally situated near the code you wrote.
If it's really a matter of performance, then I agree. However, in today's web applications, performance on such a low level is almost never a concern. From what I've learnt, it almost always boils down to IO in a loop or other nested loops with cubic complexity.
Apart from that: readability > performance. Unless you're working in game industry or doing other low level stuff.
I've spent a long-time in open source. The one thing that invariably remains…the source code (and it's git history). All other things rot and decay far faster.
So, include whatever comments can help provide contextual support of the local "state" of the code.
In addition, one must consider that placing way finding comments in a code-base are of high value.
There have been a few cases, where past decisions/specs were lost but we still had code. I don't want to go and "backfill" those specs, so I'll write a note saying "This is my understanding given what I've been able to piece together."
Okay, maybe I am viewing it too much from a business perspective. It seems like there are a lot more specs from a non-technical view there. This somehow eliminates the need for specs inside code.
If you use comments as way to communicate with other developers working on the same code base and have no real communication channel outside of that, then I can better understand the necessity!
We're both looking at the same "elephant" but from different perspectives. The code is the most accurate representation of the product. It says exactly what the product is. There will invariably be cases where the intention of the code will be hidden in a private Slack channel, a lost email, or even an unrecorded Zoom meeting.
The code is the product and provides the most reliable place to "pin" a way finding comment/annotation.
Specs inside code are…treacherous. A URL in the code to that spec? Gold!