DevChunks

Thoughts on Code Comments

Commenting on your code is an essential part of keeping your projects maintainable. It will save you and your team time in the long run.

Over-commenting is a problem. Explaining every last detail creates noise and makes your project harder to work on.

Consider the following:

Less is More.
Say just enough to clarify any unusual situations. Most of the time, your code should do the talking.

Make it Readable
Write the comments for somebody else. Avoid abbreviations that only you know. Write clearly and concisely.

Work in Progress (and TODO: )
In most IDE’s a comment starting with “TODO:” will be highlighted and searchable. Take advantage of this when your code is a work in progress, or you are waiting on something else before fixing/improving.

Update Your Comments
When you modify code, update or remove any comments no longer relevant.

Use Links
Link to API documentation, GitHub issues, or anything relevant and useful.

Leave Your Contact Details
Every team works differently, but leaving your initials or email will help others in the future.

Why So Serious?
We aren’t robots, so add a bit of your personality to lighten the mood. It may make that painful refactoring task a little easier for you or someone else.

Share:

2 Responses

  1. Sometimes you just don’t have the time and if you know for a fact the comments will not be used, I think it is more pragmatic to just forget them.

Leave a Reply

Your email address will not be published.

More Posts

How to use PHP Type Declarations

PHP has developed into a more strictly typed language in recent years. Type Declarations help with that and are a fairly new addition to PHP,

Iteration

If you have come to JavaScript from a background in Java or C, then you will like the variation on the for loop. It is

Context Object Manipulation

One of the key concepts of JavaScript is the keyword this, which signifies the JavaScript context object. If you write an inner function, you can access

Polymorphic Functions

It is possible to define multiple functions with the same name in JavaScript, and the last one of those that you define will be the