Tips to Comment the Code
description
Transcript of Tips to Comment the Code
www.softheme.com
Tips to Comment the Code
based on 13 Tips to Comment Your Code
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
1. Comment each level
Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it isacceptable and even advisable to use comment conventions and tools (such as XML inC# or Javadoc for Java) to facilitate this task.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
2. Use paragraph comments
Break code blocks into multiple “paragraphs” that each perform a single task, thenadd a comment at the beginning of each block to instruct the reader on what isabout to happen.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
3. Align comments in consecutive lines
For multiple lines of code with trailing comments, align the comments so they willbe easy to read.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
Some developers use tabs to align comments, while others use spaces. Becausetab stops can vary among editors and IDEs, the best approach is to use spaces.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
4. Don´t insult the reader´s intelligence
Avoid obvious comments such as:
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
This wastes your time writing needless comments and distracts the reader with detailsthat can be easily deduced from the code.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
5. Be polite
Avoid rude comments like, “Notice the stupid user has entered a negative number,”
or “This fixes the side effect produced by the pathetically inept implementation of
the initial developer.” Such comments do not reflect well upon their author, and
you never know who may read these comments in the future: your boss, a
customer, or the pathetically inept developer you just insulted.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
6. Get to the point
Don’t write more in comments than is needed to convey the idea. Avoid ASCII art,
jokes, poetry and hyperverbosity. In short, keep the comments simple and direct.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
7. Use a consistent style
Some people believe that comments should be written so that non-programmers
can understand them. Others believe that comments should be directed at
developers only. In any event, as stated in Successful Strategies for Commenting
Code, what matters is that comments are consistent and always targeted to the
same audience. Personally, I doubt many non-developers will be reading code, so
comments should target other developers.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
8. Use special tags for internal use
When working on code as a team, adopt a consistent set of tags to communicateamong programmers. For example, many teams use a “TODO:” tag to indicate asection of code that requires additional work:
int Estimate(int x, int y)
{
// TODO: implement the calculations
return 0;
}
Tag comments don’t explain code; rather they seek attention or deliver amessage. But if you use this technique, remember to follow up and actually do whatthe message is asking.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
9. Comment code while writing it
Add comments while you write code and it’s fresh in your memory. If you leavecomments until the end, it will take you twice as long, if you do it at all. “I have notime to comment,” “I’m in a hurry,” and “The project is delayed” are all simplyexcuses to avoid documenting your code. Some developers believe you shouldwrite comments before code as a way to plan out your ultimate solution. Forexample:
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
10. Write comments as if they were for you (in fact, they are)
When it comes to commenting code, think not only about the developers who willmaintain your code in the future, but also think about yourself. In the words of thegreat Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on thatpiece of code.”
As a result, we ourselves will be the first beneficiaries (or victims) of our good (orbad) comments.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
11. Update comments when you update the code
There is no point in commenting correctly on code if the comments are not changed
with the code. Both code and comments must move in parallel, otherwise the
comments will actually make life more difficult for developers who maintain your
code. Pay special attention to refactoring tools that automatically update code but
leave comments unchanged and hence obsolete in the same instant.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
12. The golden rule of comments: readable code
One of the basic principles for many developers: Let your code speak for itself. Although onesuspects this movement is led by programmers who do not like to write comments, it is truethat self-explanatory code can go a long way toward making code that’s easier to understandand can even render comments unnecessary. For example, the code in my Fluid Interfacesarticle shows how clear self-explanatory code can be:
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
In this example, comments are not needed and would likely violate tip #4. To facilitatereadable code, you might consider using proper names (as described in the classic Ottinger’sRules), ensure correct indentation, and adopt coding style guides. Failure to comply with thistip may result in comments that seem to apologize for bad code.
www.softheme.com Outsourcing to Softheme™ Tips to Comment the Code
13. Share these tips with your colleagues
Although tip #10 shows how we ourselves benefit immediately from good
comments, these tips will benefit all developers, especially in the context of team
working together. Therefore, feel free to share these commenting tips with your
colleagues to create code that is easier to understand and maintain.
Thank you!
2010 | Softheme Team | Kyiv, Ukraine | Software Outsourcing Solutions
www.softheme.com » Outsourcing to Softheme™
Questions? → [email protected]