A Guide to writing to better comments
Tags: beginners, productivity, java, codequality
Published: 2022-01-16 23:22:24

## 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u57obznnve450cconcvv.png)
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/umtn14gpsu3kd9yeg7ex.png)
 
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8yjyud10vmvepgnnwrk3.png)
 
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vmqsphkf4zxz64lu771k.png)
 
After cleaning it up
![good code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tsz7950s8v6138x87e8k.png)

### 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/arhaaxo6hj9xwondb10a.png)
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iomphuwjkwz2sf3ycgay.png)
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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/amao4tevyuqdqqx96l49.png)
Readers can follow the link provided in the comments to learn more
 
### 7. Comments should not be used for attribution
![Attribution comment](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/97u0u0j1wh138nx1wjjm.png)

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)