8 Tips to Improve Comments in Your Code

Published in

codeconnector

4 min readMay 12, 2020

I have a problem; I know code should have comments but I don’t know how to write good comments or alternatives to commenting. I was given a take home project for a job interview. As a hot shot aspiring developer I went crazy writing code. The app looked beautiful, the code worked, and I documented every line of code.

I decided to ask for code reviews from the local tech community. The feedback was overwhelming “you have too many comments”. The following are eight tips I received that have made me into a better and humbler developer.

#1: Before writing a comment, first ask if this code can be written in a way to eliminate the need for a comment.

This one rule is the rule for all other rules. You should follow good coding practices like great variable naming habits and breaking big functions into smaller ones.

#2: Comments may mean your code isn’t “Expressive Enough”.

I love this one and my mind nearly exploded with the shocking revelation.

This is bad.

This is good.

#3: Add comments when there is some funky logic in the code or context that you need future developers to understand.

This makes perfect sense. Comments are to help a future you or another developer understand what the heck is going on.

Why check if the response is false and what is a prediction? OK, now I see why comments are important!!!

Without the comments this may be confusing

#4: Comments should describe the “Why you wrote this function” instead of “What this function is doing”.

Look Mom, I’m a genius. This is an example of what NOT to do.

**#5: If using block comments above a function, start on the second line and have a * for each line.**

Do this and give yourself the angry father stare of contempt and disbelief.

**#6: /* */ should be used for multi-line comments and // for a single line.**

I know this should have been common sense but I’m the greatest developer of all time. Being in the “coding flow” doesn’t justify bad coding habits or time wasted fixing simple mistakes. This is a guideline, not a hard rule, for consistency and making your code easier to read.

Do not ever ever ever ever do this!! EVER.

#7: Comments should have a space between the “//” and the first word.

Once again, this is a guideline for consistency and making your code easier to read. Do you see a pattern forming? Also, if you use a linter this rule will save you hours of clean up (shout out to Autumn Ragland for this helpful reminder). ESlint has a rule that will scream at you.

In all honesty, I didn’t know better.

#8: Comments should start with a capital letter.

I was writing code so fast my fingers were on fire but the brain was turned off. This inattentiveness led to hours of refactoring countless uncapitalized first letters. ESlint has a rule for this also.

The code reviewers passed on some resources to help me learn more.

I want to give a shout out to the Memphis, TN tech community that unselfishly gave me code reviews for my projects and lots of advice on great coding practices. There is an old saying that quotes, “It takes a village to raise a child”. Well, it takes a community to train a developer.

You can follow my journey doing #100DaysOfCode on Twitter at JCSmiley4 or connect with me on LinkedIn at JC Smiley Jr. As always, let’s have fun and do lots of victory dancing.