Is comment required?

Comments are used to describe the code for other users who will reuse or do changes on that code. After few time comments are also very useful even us to realize that what we done in there. So developers used to add comments in everywhere of the code. Is it the best practice?

Add comment isn’t a best practice always. It is better if we can write descriptive code rather than adding comment to describe what we do with the code. If a code can read and get what it done that kind of code says as a descriptive code. Let’s see some example.

or we can change the code as

Which one is more descriptive? In second one it is easy to understand what it done even without a comments. Also it save the time that we wast for adding comments.

But some comments are important and we couldn’t miss. First one is legal comments that contains details about authorship and copyrights. Legal notes are generally added at the start of each source file.

For a example Oracle added Legal note like this in every sources of its products

Also there are some points that we should mention some useful information in comments.

In here we inform the user who refer the code that what do with this property and what can do with change it. At that point comment is very important and it added some value to the code.

Another useful comment is //TODO comments. TODO comment explains what are the features that should implemented but can’t done it now for some reason.

Comments can be use to amplify the important of something that can feel another user as useless.

Javadocs are very important when you are writing public APIs

Rather than that most of the other comments aren’t added much sense on the user except repeating code content to the user. Let’s lock some example comments that we can eliminate from our codes.is

Try to avoid Separator comments because with modern IDEs no use of those separators.

Don’t use comments to keep in track with version histories and author’s details. Modern version controllers manage this task much better. So don’t pollute the code with those things.



Also don’t remain unwanted commented codes in your sources. New comers will not be remove those commented codes unless you remove it. It any code really unwanted delete it without comment it.

When a code is written in first time developer properly organize the code and properly add comments. There is no problem with the code. Problems began when we had to refactor the code urgently as usually happening. Developers quickly done the refactorings and done it in time but most probably they missed the comments to refactor. So there remains irrelevant comments with the code.

Comments are very important but unwanted comments are headache for developers. So think before adding a comment if it’s really useful and be sure it says that actually done.

Next developer only get that we remains on the code. If we didn’t do nicely it’ll be a huge mess for them.

4 thoughts on “Is comment required?

  • May 17, 2016 at 6:45 am
    Permalink

    Very informative article post.Really looking forward to read more. Fantastic.

    Reply
  • July 6, 2016 at 3:20 pm
    Permalink

    Hey, thanks for the blog. Really Cool.

    Reply
  • August 17, 2016 at 10:54 am
    Permalink

    Thanks very nice blog!

    Reply
  • August 20, 2016 at 2:07 pm
    Permalink

    Great article! We are going to be linking to the particularly great content on our website.
    Maintain the truly amazing writing.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *