Your code doesn’t need to be commented. Or does it? Clear code needs to be easy to read. You may not be the only one who has to maintain this code. Write comments so the future person who updates this code can understand why you did things. Remember that person may be you.

Use these tips for commenting your code for the better.

1. Comments should be meaningful

They shouldn’t duplicate the code. Comments should compliment your code. You write to explain why the code works this way.

2. Add comments when fixing bugs

It helps you to understand what changed and why. Include references to issue numbers to provide further information. Anything else that you used to help solve the problem.

3. Add links in comments when you copy code

Everyone codes code they found on the internet. It helps to add links in the comments so you remember where you got the code from. Add who wrote it and what problem it fixes.

4. Sometimes your code isn’t finished

Use comments to remind everyone that there are limitations to this piece of code. Add TODO to remember what you need to finish.

“You should first strive to make your code as simple as possible to understand and without relying on comments as a crutch. Only at the point where code cannot be made easier to understand should you begin to add comments.”

-Jeff Atwood, Code tells you how, comments tell you why

5. Comments should explain why you did something

If your comments are confusing, remove the comment. Keep comments that are clear and easy to understand.

6. Keep your comments brief

Comments can take time to read. You want to make them as short as possible.

7. Remember to update your comments

As you change your code, your comments may need updating to reflect changes.

Comments can’t fix or excuse bad code. They should compliment it. Commenting your code should help you understand why you chose to do something.

For getting better at writing comments, read Best practices for writing code comments.

Anything else that you used to help solve the problem.