What makes well-commented code? πŸ“ƒ

There are lots of opinions on what makes well-commented code; we can't really define absolute universal rules. But I have found some guidelines are quite useful:

βœ… - Code without comments is suboptimal.

βœ… - Too many comments (one per line, for example) is probably a sign of poorly written code.

βœ… - Comments should explain why, not what. They can optionally explain how if that's particularly confusing.

Any other guideline that we should consider when documenting code?

Did you find this post useful? Show some love!
DISCUSSION (18)

I actually mainly dropped comments in the code I write. Function names, variables name should be self explaining. If I feel the urge to put a comment explaining what I do inside a function, it means that I need to make another function.

Comments looks like dead code to me, they are difficult to refactor, they add to maintenance and feel redundant most of the time too.

The only comments I write are links to some specifications or a link to an algorithm explanation.

True! I find myself adding lots of links to other resources or stack overflow explanations.

I read an article way back on what to comment. I don't comment on what my code is doing. I comment only two things.

One is the general structure of the whole project without giving any specific implementation details (only talking abstractions).

And the second thing I comment is why I decided to go a particular way to solve a problem. Suppose there is a bug or a new feature to develop. I would do my research and mostly find I can solve it in multiple ways. I just leave a small summary of my research and the links I read from and also a reason why I'm choosing one method over another.

IMO what code is doing should be self-explanatory via naming of functions and variable names. Comments should answer questions code cannot.

Interesting. Do you have the link to the article? Would love to check it out.

I'm sorry I don't remember the article and I'm unable to find it

Modules, classes and functions should have good comments on when to use them and how.

As for the code, beside what other said I would add

  • Any code that does not look optimal or clean code, I would explain why it got to this state, probably is an optimization or something that new devs wouldnt know
  • code that doesnt look optimal but it is, knowing the compiler rules,

ex: extracting a formula into a function for readable code a junior may refactor with the call overhead in mind, but the compiler will do that "inline func"

Basically comments are for things that are not obvious from the code, from a junior or new dev in team perspective.

True. When working on a team I find myself paying more attention to well written comments.

I disagree, as mentioned below, good code is self-documenting. Or at the very least it should be clear on what it does. Comments have their use but if you have to explain your code then you should re-consider your naming scheme and the way your code is structured. Check out the chapter on comments in the book The Clean Code by Robert C. Martin. Any developer would benefit from reading this book IMO.

I usually comment on what a class or function does, so that anyone can know their functionality at a glance. Helps with my own understanding as well especially when the code base is huge. Commenting on certain lines that use an external library also helps me to understand the line of code within my own code base, without having to read the documentation online.

Too many comments (one per line, for example) is probably a sign of poorly written code.

Definitely, I think you can always group some parts of your code together (5-10 lines) and tell what it does in one line of comment.

Code without comments is suboptimal.

In some cases comments just don't help at all, they are simply repeating what the definition of the function/method/class does.

Comments should explain why, not what.

I don't really understand this one...
Should it explain why a function/method/class exists? Or why you should use it? Here is my train of thought:

Needs method that gets the capacity of a list -> sees size as a method -> does it do what I want? -> looks at comment that says "Gets the current capacity (the number of elements it can store) of the list" -> uses it.

My view on this is quite different (as you can see from this video). In this situation I think it's ok to tell in your comments what that method does.

I write code in increments, by block for example, to explain what the code preceding does. This makes it easy for new devs to hit the ground running as well as understand overall composition.

If you can make blocks, usually, you can make a function too ;)

I think this kind of guide helps a lot! Thanks Lauro! Your posts are awesome, keep going!
Hugs & Husky love! πŸΆπŸ‘©πŸ»β€πŸ’»

I actually only comment classes, methods and properties to have a nice doc.

In code, I switched from commenting to debug or trace logging, it's two birds with one stone.

Classic DEV Post from Oct 16

Thoughts on GitHub Actions?

GitHub just launched β€œActions” GitHub @github Automate your workfl...

Lauro Silva
Software Engineer and Technical Writer.
Join dev.to