Login | Register   
LinkedIn
Google+
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


Tip of the Day
Language: Java
Expertise: Beginner
Nov 19, 1998

Add Documentation to Identify Sections in Your Code

With embedded combinations of loops, conditions, and try / catch statements, it can be difficult to keep track of where each section ends when quickly scanning your Java code, even with the help of indention. For example:
 
public method doSomething(Object value) {
	int value;
	if (value instanceof String) {
		try {
			value = Integer.parseInt(value.toString());
		}

		cach (NumberFormatException nfe) {
			value = -1;
		}

	}

	else if (value instanceof Integer) {
		value = ((Integer)value).intValue();
	}

}
With complex combinations, these blocks are not only difficult to separate visually, but they can also be difficult to debug if you accidentally omit a closing brace. The situation can be improved by adding documentation that identifies the end of a given section:
 
public method doSomething(Object value) {
	int value;
	if (value instanceof String) {
		try {
			value = Integer.parseInt(value.toString());
		}  //  try

		cach (NumberFormatException nfe) {
			value = -1;
		}  //  catch (NumberFormatException nfe)

	}  //  if (value instanceof String)

	else if (value instanceof Integer) {
		value = ((Integer)value).intValue();
	}  //  else if (value instanceof Integer)

}  //  public method doSomething(Object value)
This technique is especially helpful for very long blocks of code, where the closing brace does not appear on the screen at the same time (or same page of a printout). The programmer can then easily identify the beginning and end of a section of code by using a combination of indention and the comment describing the start of the section.
Brett Spell
 
Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap
Thanks for your registration, follow us on our social networks to keep up-to-date