Clean Code - Comments - by Uncle Bob - part 2

[bpoplauschi]

No description provided.

[kareemjeiroudi]

I don't entirely agree to uncle Bob's view on comments to be honest. While it's true that comments should be your last resort, and that code should explain itself like plain English, comments are often your best friend, and not your biggest enemy as seen by many fellow programmers.

Comments rot quickly and silently

I hear this argument quite often. This is sooooooo inaccurate. EVERYTHING in the code base is prone to rot (including comments), and there's a good reason for this misleading saying: unfortunately big part of programmers don't read comments, or don't bother to update them because: a) comments don't cause any compilation errors. b) your IDE doesn't prompt you whenever you comment is outdated or doesn't match the code. c) (let's be honest) most of us can't wait to get the job done, and tend to avoid any extra unnecessary work, which is both wise and evil.

I would rather argue that it's the programmer's duty to make sure that comments always sync with code. This, of course, implies removing a comment if it's no longer necessary or causes confusion to the reader. However I'm completely against discouraging programmers to comment their code.

Obviously, you should keep security & privacy concerns in mind when writing comments, such as not to include credentials or API keys, but I think that applies to strings too. So, again, it's not specific to comments, but please be careful with that.

While you're at, do it instead of leaving TODOs

TODOs are a very good example for areas where the implementation isn't complete yet, however, you cannot tell how long it would you take you to finish that part of the implementation. Issues are often time-boxed and sometimes you would need to get out of the story's scope to finish that part. It's why you leave TODOs. It's not because you already have the solution, but you're just too lazy to write it. It's rather because you would need to do extra research on that part of the implementation, and try out different scenarios, and test what solution best fits your implementation... etc.

Avoid Mumbling

Mumbling comments (imo) are some of the best means to explain your concerns/thought-process to your reviewer (or fellow programmers). Those are usually super urgent comments that you can't wait to write down, because you'll forget about in less than 5 minutes. So you can't wait to get to the merge review to express these concerns, not-to-mention the possibility that you've already forgot what you had to say about your code. I happen to enjoy mumbling a lot, and found that it often leads to good productive discussions during the code review. Eventually, most of these comments get resolved or removed before the changes are merged, some remain, but it's rather a good technique. Quite the opposite - please mumble! Don't hesitate to leave your thoughts between code lines - if you think they're easy to skim.

Shift your attention to more serious topics

My last argument is that you can always undo/remove comments. It takes less than a second. It's why I find it rather amusing that this is such a big deal for programmers, whether or not you should leave comments. People go all the way to categorize it as "clean or non-clean code". In my experience there are much more serious topics in programming that need to be addressed than to write or not to write comments. If comments are you biggest worries, then I hope it remains so.

Final word

It should really be up to each team to decide whether or not they want to include comments in the source code, and if so, what type of comments. Like I mentioned earlier, I happened to find them useful in many cases, there are actually good tips on how you can leave good readable and meaningful comments to others in your code.

[bpoplauschi]

Good points @kareemjeiroudi, thanks for sharing. I agree that how to deal with comments should be decided by each team. In my case, I lean towards using them only as a last resort. I try my best to use the code (private variable names, private function names, ...) to describe my intent or other useful info, and when I can't, that's when I resort to comments.