Java supports three kinds of comments: documentation, block, and single-line. These are described separately in the subsequent sections below. Here are some general guidelines for comment usage.

  • Comments should help a reader understand the purpose of the code. They should guide the reader through the flow of the program, focusing especially on areas that might be confusing or obscure. Avoid comments that are obvious from the code, as in this famously bad comment example:

     i = i + 1;      // Add one to i 
  • Remember that misleading comments are worse than no comments at all.

  • Avoid putting any information into comments that is likely to become out-of-date.

  • Avoid enclosing comments in boxes drawn with asterisks or other fancy typography.

  • Temporary comments that are expected to be changed or removed later should be marked with the special tag "XXX:" so that they can easily be found afterward. Ideally, all temporary comments should have been removed by the time a program is ready to be shipped.


 // XXX: Change to call sort() when the bugs are fixed        list->mySort(); 

Software Development. Building Reliable Systems
Software Development: Building Reliable Systems
ISBN: 0130812463
EAN: 2147483647
Year: 1998
Pages: 193
Authors: Marc Hamilton © 2008-2017.
If you may any questions please contact us: