Comments, while being the most underrated part of any program, can play a significant role in how the development process goes. Although the commen...
For further actions, you may consider blocking this person and/or reporting abuse
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.pushorrenderin 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.
Is it only me, that I use
/** */everywhere, because of VSCode convenience? (Regardless of single line or multiple lines.)@annotationandTODO:might appear as well.You might even go for Better Comments.
//is usually generated fromCtrl+/, 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/* */.)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
Agree with everything except for number 4. If your code has bug/unexpected behavior it should be documented in comments. Creating a GitHub issue or Jira tickets is definitely beneficial, but there is no guarantee the other developers will look at external sources while working on the code.
Yeah, I always had a doubt either to put that or not. decided to let you guys do the choice for me. 😊
Haha I love the "Zombie code 🧟♂️" term!!!
About 4. I would say that a comment is not bad if prefixed with
// TODO:. Even maybe better if the todo reference an issue in the tracker as you suggest.Thank for the share 👍
I got used to using
// FIXME:for these scenarios so they stick out. A bug should be higher prio than a normal todo in my opinionOh pretty cool tips and tricks 👍
Do you use
// TODO:and// FIXME:"only" or any other granularity?// @TODOfor things that should be improved/refactored in the future.// @FIXMEfor things that are in a broken/buggy state.There is a risk that nobody will ever look at these comments again and they remain there to rot in the codebase. This works best if you add a ticket number from your issue tracker (Jira/GitHub issues) so any developer can find context information about it, so:
// @FIXME #321: Temporary fix for XYZ, remove when this ticket is doneI use this one here marketplace.visualstudio.com/items...
Apart from TODO and FIXME I also use
// HACK:😆 That's about it@alexanderjanke : Haha I might use the
// HACK:way more often than it should be allowed 😅. Thanks for feedback, might probably gonna try to enrich my todos with these ideas.@ekeijl : Agree with you, works best with a ticket number, if not even a must
Nice article. For me, I don't encourage adding comments at all :D. Because I feel they are an acceptable workaround for writing unclear code 🙉, and that is why I totally agree with you on the first point.
But the only case I would write a comment is when the intention behind adding this function or functionality is ambiguous. So in a short sentence, I would add comments about "why" I wrote something instead of "what" I wrote.
I don't write comments when I am coding either 😋
But when I am done writing, I review the code and then comment out some unclear parts.
I never take the time to comment. I do write a lot of "zombie codes" tho :P
Excellent article and advice! Thank you!
Does someone know the official term for "zombie code"?
"Commented out" code