DEV Community


Discussion on: Clean code & programming principles – The ultimate beginner’s guide

sargalias profile image
Spyros Argalias Author • Edited

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:

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

Edit: changed "Todo class" to "Todos model class"

tilkinsc profile image
Cody Tilkins

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.

Thread Thread
sargalias profile image
Spyros Argalias Author

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