Comments, while being the most underrated part of any program, can play a significant role in how the development process goes. Although the comments are ignored by the compiler or the interpreter, there is no reason for you, as a developer to ignore writing them.
However, you need to write comments doesn't mean you will put a single comment in the whole code or just write a comment in each line. You should follow some good practices to help your fellow developers or the future you to maintain the code better.
1. Write meaningful names, not comments
Follow good naming conventions for functions, variables, objects etc. You don't need to write a comment to mention what kind of value variable stores.
Instead of doing this
function Funtion1(r) {
// this function returns the area of a circle
// r is the radius of the circle
return 3.1416 * r * r;
}
You can done this
function CircleArea(radius) {
return Math.Pi * Math.Pow(radius, 2)
}
As you can see, a good naming practice saved 2 lines of comment.
2. Keep it simple, keep it short
At the end of the day, the sole purpose of a comment is to make the code more readable, not to confuse the developer trying to contribute. Keep it as simple as possible. Try focusing on keywords rather than trying to fix grammatical errors. After all, you are writing code, not a novel.
function SyntaxHighlighter(code) {
// this function first takes the code as input then highlights the keywords in the code by wraping with <span>. After that it returns it.
...
}
function SyntaxHighlighter(code) {
// returns the syntax highlighted code
}
It wasn't necessary to put a comment in the second code at all as the function name describes the purpose pretty well, but you got the point. 😋
Also, always remember, You are writing comments, not documenting your code. Yes, some of you might argue that commenting is somewhat like documenting code. Yes, I agree too. But this is just a small part of a bigger picture. So for now, just don't.
3. Do NOT add your biography
I have seen enough codes where people go insane and add up as much information as they can in the comment thinking that if other people copy paste their codes, their name will still be in the comments. 🤦♂️
I think they don't know there exists a button in the keyboard called Backspace
/*
Author Name: ABCD WXYZ
Date created: 1/2/2011
Language: Javascript, HTML, CSS
Code Editor: Visual Studio Code
Eye Color: Green
Favorite Color: Blue
Favorite Car: Ford Mustang
Father's Name: ASDFGH
Mother's Name: QWERTY
*/
Why?! Just why?!
4. Don't comment on what bugs the code has
Commonly, you know a specific part of the code is causing some error but you don't have the fix. So, you just commented out that a particular part of the code doesn't work.
function MyFunction(something) {
... // This code doesn't work because that code does
}
There is nothing wrong with putting a comment like this. However, I suggest keeping notes of bugs(use the "issues" if you are using Github) as it will help you in the long run if you face the same error again.
5. Avoid zombie codes 🧟♂️
But what is a zombie code? 🤨
Well, I don't even know if "zombie code" is an actual term in programming. I just came up with it while writing this blog. Here is an example.
// function CircleArea(radius) {
// return Math.Pi * Math.Pow(radius, 2)
// }
Makes sense? As you can see, this is a functional code, but disabled. As I mentioned earlier, if you are using some kind of version control system, you don't need to comment out part of a code if you think you don't need it now, but it might be useful later. Just delete it and let the version control system handle the rest.
Well, yeah, this is what I had to say today. Let me know what practices you follow when writing comments.
I wrote the whole thing while attending an online class as I became bored. Forgive me if you see something wrong in here 😋
Top comments (17)
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
Some comments may only be visible to logged-in visitors. Sign in to view all comments.