DEV Community

Cover image for My take on commenting code - Explain why, not how

My take on commenting code - Explain why, not how

Keff on May 13, 2022

// This is the start of the article Enter fullscreen mode Exit fullscreen mode Ohh damn, couldn't have figured that...
Read full post
Collapse
 
katafrakt profile image
Paweł Świątkowski • • Edited

For me, the most important reason to write the comments is when I know that the code in question is counterintuitive. For example, a code that I wrote yesterday:

total = 0
products.each { |p| total += p.price * p.quantity }
total
Enter fullscreen mode Exit fullscreen mode

This code screams USE MAP DUDE:

products.map { |p| p.price * p.quantity }.sum
Enter fullscreen mode Exit fullscreen mode

Well, as it happens, products is not an array, but an object from an external library, that implements each but doesn't implement map (don't ask). I know that me in 4 months and any other person might not remember that and will sigh and try to refactor this code, only to fail. That's why I'd put a comment explaining why this code looks this way.

Collapse
 
nombrekeff profile image
Keff • • Edited

Fantastic reason, thanks for sharing!

And a really nice point, adding comments when refactoring, renaming or creating a new method is not possible, for example for 3rd party libraries, as you mentioned! This would fall into the "comment why not how" idea, as you can't control the how in this case.

Collapse
 
auroratide profile image
Timothy Foster •

Code comments are intended to add more context to your codebase, in case the code itself is not enough

Completely agree! Or as I like to put it, comments tell you what code can't tell you.

Collapse
 
nombrekeff profile image
Keff •

Nice way to put it, might use it in the future ;)

Collapse
 
gudata profile image
gudata •

Here is one more usage of the comments in order this article to be complete.

When I want to write something with multiple steps I like to draft them as

# Do first
# for each item
# do something else
# Do final thing
Enter fullscreen mode Exit fullscreen mode

So then I implement the logic bellow the comments

first()
for each item in items:
  something_else()
final()
Enter fullscreen mode Exit fullscreen mode
Collapse
 
nombrekeff profile image
Keff •

Fantastic addition, I also do this, it's a simple way to map out your ideas. I either do it with comments or using a markdown file, I prefer using markdown as I can then keep a log of what my thought process was at the time!

Collapse
 
aarone4 profile image
Aaron Reese • • Edited

My main language is SQL and comments are vital, especially where code is there to explicitly get around a data quality issue that may be temporary
Not stated in the article but PLEASE use /+block comments+/ rather than //line comments. (Use stars not plusses: Dev editor removes stars!)
In the event that some repo or copy-paste removes line breaks block comments won't break or change the behaviour of code.

Collapse
 
nombrekeff profile image
Keff •

Good points, I'll take note on them!! I see why comments are essential when writing SQL.

I've never thought about the issues of using line comments, have you ever encountered an issue using them? Or is it a rare scenario?

Collapse
 
simeg profile image
Simon Egersand 🎈 •

I've heard reasoning for both sides (comment a lot vs. never). I agree with you though. I try my best to avoid comments but sometimes it's warranted.

My decision making is something like "will myself or someone else be confused by this code (that I can't, for some reason, make cleaner) in a month? Better add a comment".

As I've gotten more experienced with programming, the less comments I write. But the more docs (Java docs for example) I write.

Thanks for sharing! Good stuff.

Collapse
 
nombrekeff profile image
Keff •

Thanks for reading!! I agree with you as well, there's times that it's difficult to make clean/understandable code with the time we have to work on it. So adding a comment can be a good solution!

Collapse
 
andrewbaisden profile image
Andrew Baisden •

Without commenting we would probably get lost in an unfamiliar codebase.

Collapse
 
nombrekeff profile image
Keff •

Interesting, in which way would you say they help you navigate codebases? Have you ever felt the opposite way in any codebase?

Would you mind sharing some of these comments so we can better understand what you mean?

Collapse
 
andrewbaisden profile image
Andrew Baisden •

Sometimes it's not always obvious what a block of code is doing. Every developer has their own way of setting up a project architecture. So commenting can help to get someone up to speed if onboarding them with another developers help is not an option.

Constructive comments are always welcome. The VS Code extension Better Comments is a good example of comments done well.

Thread Thread
 
nombrekeff profile image
Keff •

Ohh okay, I see where you're going. I have to agree. This is in part what I was referring with explaining why you do something and explaining things code can't explain. Context on how a project is architected and why things are done in the way they're done. I also welcome these kinds of comments, and write them myself. I have no problem with them. My issue is mainly the comments explaining obvious or convoluted code, that could be better of just by refactoring and naming stuff correctly

For me these types of comments fall just in the line between code comments and doc comments.

Cheers, and thanks for the addition!