I think it would be worth mentioning commenting, as it makes the 'we dont remember anything' non-existent. Proper commenting explains context, inputs, outputs, and intended purpose.
Front end developer specialising in JavaScript and React. Experienced in all aspects of modern front end development. Passionate about making accessible, secure and performant software.
I actually have a stance against commenting, just like Uncle Bob.
Reasons I advise against comments
If you use good names and good code organisation you don't need comments.
For example, if your method is named "addTodo", in your Todos model class, you don't need a comment to describe what it does. The name already describes it enough. A comment would be redundant. This is how it should be with all code, naming and comments.
If you need a comment to explain something, the code could have been simpler and better labelled (named) so the comment wouldn't be needed.
If you need comments to explain connections and dependencies that you wouldn't otherwise know were there, then the code isn't independent / decoupled enough. It should be refactored so that the comment is not necessary.
Also, comments make changes more difficult. If you update or change something in the code, you need to also change any relevant comments, which is additional work that slows you down.
Finally, someone may not update the comment when they change the code. Then, you have an even bigger problem on your hands because the comment now says wrong information. But, the next developer to read the comment wouldn't know it's outdated. The comment may say something like "this is dependent on X". The developer may investigate further, only to waste their time, because the comment is no longer true. Or they may be afraid of changing anything because of the comment. Or there could be many other problems.
In summary, my reasons are that:
comments should not be necessary
comments are additional work to update
comments may be outdated and contain false information, potentially causing large problems
Therefore, I avoid comments in almost all of my code. I've also worked in many codebases. The ones that didn't use (need) comments were substantially easier to work in.
Exceptions and other cases
The only rare exception, is if you're working in some especially bad area of the codebase. If you need a comment to point out something important, you write it, but that should be the exception. In my experience, that's only been in areas with bad code in the codebase.
I think commenting as documentation is fine though. E.g. if you have a tool that picks up comments in code, written in a certain format, and auto-generates documentation for them.
Also, I think documentation about your code is fine. That's documentation that, for example, describes the architecture of your code, main classes and how they fit together. These are different from detailed comments in code. They're more like an introduction to your codebase, or certain parts of it, for new developers to the company or the particular team.
But that's just my opinion. I welcome your thoughts and even counter-arguments.
What you are suggesting tends to make code bases more complicated with more steps. The problem translates into piecing together many different functions under many different hierarchies. It tends to prove that procedural programming is superior in that regard. Comments for everything is not necessary, but I've found you wonder if a specific function supports a feature. A good programmer with foresight makes comments for other users to understand edge cases as well as makes proper tests to prove that everything works.
Front end developer specialising in JavaScript and React. Experienced in all aspects of modern front end development. Passionate about making accessible, secure and performant software.
Thanks for the reply. I agree with tests and I'm a big proponent of them :).
I also agree that if a comment would be useful and save someone a headache, it should be added. My point was only that comments should be the last resort compared to code that's obvious and sensible so it doesn't need comments.
I won't be adding it to the article for now because I don't see it as part of the fundamentals. More like a tip, that also needs the appropriate warning of only using comments as a last resort.
Having said that, I really appreciate that you took the time to make a suggestion. Thank you.
Some comments have been hidden by the post's author - find out more
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think it would be worth mentioning commenting, as it makes the 'we dont remember anything' non-existent. Proper commenting explains context, inputs, outputs, and intended purpose.
Thanks for the comment @tilkinsc .
I actually have a stance against commenting, just like Uncle Bob.
Reasons I advise against comments
If you use good names and good code organisation you don't need comments.
For example, if your method is named "addTodo", in your Todos model class, you don't need a comment to describe what it does. The name already describes it enough. A comment would be redundant. This is how it should be with all code, naming and comments.
If you need a comment to explain something, the code could have been simpler and better labelled (named) so the comment wouldn't be needed.
If you need comments to explain connections and dependencies that you wouldn't otherwise know were there, then the code isn't independent / decoupled enough. It should be refactored so that the comment is not necessary.
Also, comments make changes more difficult. If you update or change something in the code, you need to also change any relevant comments, which is additional work that slows you down.
Finally, someone may not update the comment when they change the code. Then, you have an even bigger problem on your hands because the comment now says wrong information. But, the next developer to read the comment wouldn't know it's outdated. The comment may say something like "this is dependent on X". The developer may investigate further, only to waste their time, because the comment is no longer true. Or they may be afraid of changing anything because of the comment. Or there could be many other problems.
In summary, my reasons are that:
Therefore, I avoid comments in almost all of my code. I've also worked in many codebases. The ones that didn't use (need) comments were substantially easier to work in.
Exceptions and other cases
The only rare exception, is if you're working in some especially bad area of the codebase. If you need a comment to point out something important, you write it, but that should be the exception. In my experience, that's only been in areas with bad code in the codebase.
I think commenting as documentation is fine though. E.g. if you have a tool that picks up comments in code, written in a certain format, and auto-generates documentation for them.
Also, I think documentation about your code is fine. That's documentation that, for example, describes the architecture of your code, main classes and how they fit together. These are different from detailed comments in code. They're more like an introduction to your codebase, or certain parts of it, for new developers to the company or the particular team.
But that's just my opinion. I welcome your thoughts and even counter-arguments.
Edit: changed "Todo class" to "Todos model class"
What you are suggesting tends to make code bases more complicated with more steps. The problem translates into piecing together many different functions under many different hierarchies. It tends to prove that procedural programming is superior in that regard. Comments for everything is not necessary, but I've found you wonder if a specific function supports a feature. A good programmer with foresight makes comments for other users to understand edge cases as well as makes proper tests to prove that everything works.
Thanks for the reply. I agree with tests and I'm a big proponent of them :).
I also agree that if a comment would be useful and save someone a headache, it should be added. My point was only that comments should be the last resort compared to code that's obvious and sensible so it doesn't need comments.
I won't be adding it to the article for now because I don't see it as part of the fundamentals. More like a tip, that also needs the appropriate warning of only using comments as a last resort.
Having said that, I really appreciate that you took the time to make a suggestion. Thank you.