No commenters, like Riyad Mammadov, argues that good code should be self explanatory. Unit tests does a far greater job in showing how the code works, and it never goes out of sync with the production code. Comments need to be kept up too date with the code, and the coder will also need to spend time ensuring the comment is good and comprehensible. That is time that could be spent on refactoring and cleaning up the code itself.
On the other hand, commenters, like Danny Tuppeny, say it's far easier to grok the system by comments. Comments are after all written in English for people while code can be cryptic and is meant for compilers. Keeping code and comments in sync is part of being professional. Code cannot show why it's written. It's faster to understand well written and documented code than the doing the same for thousands of lines of bare code. Sure, there are bad comments, but that's the result of the code author not being professional enough.
They both have some important points. It's logical that the most consistent way is to let the code explain itself. On the other hand, the code cannot give us details about the reason something is done. A method named applyApiWorkAround() is ok, but we still need a comment for the details.
Commenters are absolutely right about that the code base will be cryptic if we remove all comments from it. But this not what the No-commenters want!
Actually, "No-commenters" is not accurate enough. "Refactorers" is more suitable. So it's Commenters and Refactorers.
I'm a refactorer myself (at least try to be one). Refactorers must be clear about their goals when discussing with Commenters. We are not against all comments. We do fancy some types documentation, for example:
- system overview and architect
- project jargon list
- general descriptions about main logic flows
- 'why' comments in code
- method doc for public apis
- our pay checks
Docs that describes some kind of overview are still duplication of the code but will stay valid for a longer period of time. The gain outweighs the time needed to update it. Our main concerns are to follow DRY and improve the readability of the code.
Commenters most powerful argument is "code is hard to read without comments". I agree that bad code is hard to read without comments. But how about methods containing 4-8 lines with excellent named and clear code? When you stumble upon a long or complex method, don't add comments. Refactor it! Even refactor that part of the system if needed. Ok, do comment on 'whys', that's good. The 'hows' are already in both the unit tests and production code. Commenting on that is duplicating the logic and just a workaround for a proper refactor.
In the end, we all want to be professional, save our team/client some bucks and make sure the project gets finished. I invite all Commenters to try refactoring the code first. Refactor it to small methods, methods that anyone can understand. Then write unit tests to show and test your new code. Oh, ideally, the tests should come first. That's TDD and is a wonderful topic for another future post.
I highly recommend the book Clean Code by Robert C. Martin for more details about writing, uhm, clean code.
