DEV Community

Cover image for A Guide to writing to better comments
Timilehin Bakare
Timilehin Bakare

Posted on

A Guide to writing to better comments

Introduction

You're probably thinking," what's new with comments?" and you'll be right to think that.
Often times, not much thought is put into writing a comment. They are mostly ignored and considered secondary(albeit as they should be) but this negligence has led many programmers into writing very awful comments.
for example:
bad comment code snippet
In order to avoid writing comments like this, I have written this article to serve as a guide to writing better comments.

Here are some guides to writing better comments

  1. Avoid writing redundant comments
  2. Comments should be updated
  3. Do not excuse bad code with commenting
  4. Comments should not reference other codes
  5. Comments should be informative
  6. Comments could be used to provide links to original source code
  7. Comments should not be used for attribution

The rest of this article explains these guides and provides examples to them.

1. Avoid writing redundant comments

redundant comments

The above is common among early-beginners as they're introduced to code, While this could be very helpful with teaching beginners. Its considered redundant as it adds no information and merely causes visual clutter.

2. Comments should be updated.

Overtime comments silently degrade. While code is continuously updated, the comments are forgotten. For a code cryptic in nature, readers turn to the comments to provide an explanation, and when that explanation is false it leaves the readers confused or worse mislead.
for example:
regex-pattern comment

The asterisks in the regex pattern show that it matches a whole lot more than it was stated by the comments which could be very misleading to the readers who do not bother to check the regex pattern.

3. Do not excuse bad code with commenting

Commenting should be used as a last resort. Every comment serves as a failure to express yourself clearly in code. Always try to clean the code to express yourself better before resulting to commenting.
for example the code snippet below could have been cleaned up rather than using a comment.

bad code

After cleaning it up
good code

4. Comments should not reference other codes

A comment should not reference a code that is not present or local because the reference code could change but the comment wouldn't
for example
poor reference comment
The comment above references a "default" that is not present in the code block, this confuses the reader as they don't know what default in the comment means.

5. Comments should be informative

Informative comment
The comment above informs the reader that SimpleDateFormat is not thread-safe, if the code is to be modified, the programmer would be well informed of its limitations.

6. Comments could be used to provide links to original source code

linked comment
Readers can follow the link provided in the comments to learn more

7. Comments should not be used for attribution

Attribution comment

Comments like these are unacceptable especially in production. The source code control systems can always tell who the author was.

Conclusion

I hope this article has been helpful in highlighting the importance of writing proper comments and the guides provided were well understood.

References: Clean code(A handbook of Agile Software Craftsmanship)

Discussion (3)

Collapse
iwashiding profile image
IWasHiding

thank you so much i really enjoyed reading your post.

i also have a one thing to add, i think that the best way to write comment is by trying to not to write comments , and make your code self documenting, where our functions and variables speaks for it self.
we should only write comments when we can not write a self documenting code.

Collapse
codebyulad profile image
Mbah Favour

Lovely post

Collapse
olanetsoft profile image
Olubisi Idris Ayinde💡

Awesome post