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.
// validate normal user exceed mounthly usage if(user.type.aquals(NORMAL) && user.monthlyUsage > usageLimit)
or we can change the code as
if(user.isNormalUserExceedMounthlyUsage())
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
/* * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */
Also there are some points that we should mention some useful information in comments.
//keep track of the current db connection status. // (initial value is false to make sure the first SNMP trap is sent when sustem starts) private boolean isDbConnectionDown = true;
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.
//todo need to check if a cycle has been missed previously and if it has been mist it has to be reloaded.
public List loadAllUnfinishedCampaigns(String schedulerTypes, JobExecutionContext context) {
Comments can be use to amplify the important of something that can feel another user as useless.
// Important- Calender months are indexed from 0-11. eventMap.put(monthField, String.valueOf(calendar.get(MONTH) + 1));
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.
// Actions ----------------------------------
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.