DEV Community

loading...
Cover image for How To Write Comments

How To Write Comments

muhimen123 profile image Muhimen ใƒป3 min read

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;   
}
Enter fullscreen mode Exit fullscreen mode

You can done this

function CircleArea(radius) {
    return Math.Pi * Math.Pow(radius, 2)
}
Enter fullscreen mode Exit fullscreen mode

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.
    ...
}
Enter fullscreen mode Exit fullscreen mode
function SyntaxHighlighter(code) {
    // returns the syntax highlighted code
}
Enter fullscreen mode Exit fullscreen mode

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
*/

Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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)
// }
Enter fullscreen mode Exit fullscreen mode

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 ๐Ÿ˜‹

Discussion

pic
Editor guide
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
patarapolw profile image
Pacharapol Withayasakpunt

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 /* */.)

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
aakatev profile image
Artem

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.

Collapse
muhimen123 profile image
Muhimen Author

Yeah, I always had a doubt either to put that or not. decided to let you guys do the choice for me. ๐Ÿ˜Š

Collapse
daviddalbusco profile image
David Dal Busco

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 ๐Ÿ‘

Collapse
alexanderjanke profile image
Alex Janke

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 opinion

Collapse
daviddalbusco profile image
David Dal Busco

Oh pretty cool tips and tricks ๐Ÿ‘

Do you use // TODO: and // FIXME: "only" or any other granularity?

Thread Thread
ekeijl profile image
Edwin

// @TODO for things that should be improved/refactored in the future.
// @FIXME for 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 done

Thread Thread
alexanderjanke profile image
Alex Janke

I use this one here marketplace.visualstudio.com/items...
Apart from TODO and FIXME I also use // HACK: ๐Ÿ˜† That's about it

Thread Thread
daviddalbusco profile image
David Dal Busco

@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

Collapse
hsalem profile image
Hassan

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.

Collapse
muhimen123 profile image
Muhimen Author

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.

Collapse
aakarshb profile image
Aakarsh B

I never take the time to comment. I do write a lot of "zombie codes" tho :P

Collapse
myzel394 profile image
Myzel394

Does someone know the official term for "zombie code"?

Collapse
tiguchi profile image
Collapse
tatacsd profile image
Thays Casado

Excellent article and advice! Thank you!