DEV Community

Discussion on: How To Write Comments

Collapse
 
ekeijl profile image
Edwin

I would like to add:

Learn about JSDoc
Using JS Doc for JS (or Javadoc for Java of course) will add a lot of value if you are working in a team. By documenting your functions with /** and using @param, your editor can pick up on this and show quick documentation when you hover the function or even show hints about parameters and types. JSDoc can even generate full API documentation in HTML.

You should explain WHY the code is there, not WHAT it does
If it is crystal clear what a piece of code does, there is absolutely no need to comment it. The same for common functions of some framework that you are using (like Array.push or render in React). The reader of your code can look that up himself. You are only wasting time of the person who has to read your comment and it makes you look stupid.

This is not black and white of course, rookie developers hardly know anything about the codebase they work with. Just keep in mind that you need to explain pieces of code that are 'out of the ordinary', for example when you are fixing an exceptional edge case for Internet Explorer 11.

Collapse
 
drbeehre profile image
DrBeehre

I agree, I think learning just how to use Javadocs or any similar can vastly improve the readability of your code base. Probably the easiest big win IMO

Collapse
 
patarapolw profile image
Pacharapol Withayasakpunt • Edited

Is it only me, that I use /** */ everywhere, because of VSCode convenience? (Regardless of single line or multiple lines.)

@annotation and TODO: might appear as well.

You might even go for Better Comments.

// is usually generated from Ctrl+/, not because of my typing. (Yeah, that zombie code.)

For Python, PyCharm already automate docstring generation, but in VSCode, you will need a plugin.

I am missing JSDoc / JavaDoc in Godoc; because VSCode won't autogenerate it for me. (Also, Go folks recommend // rather than /* */.)