A Model Intranet Application - Part 2 - Online Article

Coding Style Notes

A good percentage of the code styles here are simply done for readability. Here is a list of what I think is different and superior:

     
  • Code layout is cleaner. Comments are used.
  •  
  • Source code order is different.

Let's go over each individually and show some examples.

Code Layout

Parentheses and Code Blocking

The original Java samples and source code that come with the JDK use what is known as the K&R style of code blocking. This style places the open parenthesis at the end of the statementthat begins the block.

Listing 4. The BadKitty class-K&R style.
 
public class BadKitty extends Kitty {
       public BadKitty( int clawCount )
{      }
}

K&R stands for Kernigham (Brian) and Ritchie (Dennis), the creators of the C programming language. In their (in)famous book, The C Programming Language, this was the manner of codelayout, hence the name.

Listing 5. The BadKitty class-Non-K&R style.
 
public class BadKitty extends Kitty
{
      public BadKitty( int clawCount )
      {
      //    Code goes here!
      }
}

Using Tabs Versus Spaces

Whenever code is indented, tabs are used. Tabs keep code aligned and are portable between operating systems.

Liberal Use of Spaces

As you may or may not know, the compiler really doesn't care about spaces in your code. All white space and comments are stripped out before the actual compilation is done. Adding more spaces than necessary is another readability issue. Wherever possible, spaces are used. This might seem a bit lengthy. However, you will see the improvement. The following line of code uses no spacing:

blackBoxToUse = (myBlackBox==null) ? defaultBlackBox : myBlackBox;

And this one spaces things out nicely:

blackBoxToUse = ( myBlackBox == null   ) ? defaultBlackBox : myBlackBox;

Look how much more readable the second line is! You can quickly parse the line and understand what is going on. You don't spend time parsing.

Multiple Lines Per Statement

In an effort to make the code more readable, all class and function declarations are split into two, three, or four lines. The number of lines depends on the number of elements that make up the statement. The rules are different between class and function declarations.

Class Declarations

Class declarations can appear on up to four lines and are in the following order:

[access] class name [extends super_class] [implements interface]

Usually this declaration is made on a single line. However, by splitting it up into multiple lines you can immediately learn information about the class without even reading the declaration.

Listing 6. A beautiful class declaration.
 
public class FileDate extends Date { ... }

Function Declarations

Functions are declared in much the same manner as classes. However, the function name is always on the second line, and all other information about the function is on the first line. Functiondeclarations are always two lines long. The declarations are in the following format:

 
[access] return_type   function_name( arguments )

Listing 7. A well-styled function declaration.

public String toFileString()
{
  String retString = "";
  int m = 1 + getMonth();
  int d = getDate();
  int y = getYear() % 100;
  if ( y < 10 )
  retString += "0";
  retString += y;
  if ( m < 10 )
  retString += "0";
  retString += m;
  if ( d < 10 )
  retString += "0";
retString += d;
  return( retString );}

Comments

Comments are a sore issue with many programmers. A friend of mine (Hey Bill!) used to tell me that the only purpose comments serve are to amuse the compiler. In some cases, he might be right. Generally the comments are restricted to a single line, right above the line of code to which it pertains. This is common practice.

In addition to the single line comments, I like to distinguish chunks of code from others with the use of a block header. It serves no purpose other than to segregate blocks of code visually.

Listing 8. Comments really do improve the readability of  your code!
 
//**************************************************************************** 
//* Package &nb sp; *
//****************************************************************************
package jif.util;

//****************************************************************************
//* Imports &nb sp; *
//****************************************************************************
import java.util.Date;

//**********
//* Date *
//**********

/**
* An extension of the default Java Date.
*
* @see java.util.Date
*
* @version 1.00, 1 May 1996
* @author Jerry Ablan, munster@mcs.net
*/

public class FileDate extends Date
{

//************************
//* toFileString &nbs p; *
//************************

/**
* This method returns the date in a format suitable for using in
* file names. This format is YYMMDD, where YY is the year, MM is the
* month, and DD is the day.
*
* @see java.util.Date#toString
*/

public String toFileString()
{
String retString = "";
int m = 1 + getMonth();
int d = getDate();
int y = getYear() % 100;

if (y < 10)
{
retString += "0";
}
retString += y;

if (m < 10)
{
retString += "0";
}

retString += m;

if (d < 10)
{
retString += "0";
}

retString += d;

return (retString);
}
}

About the Author:

No further information.




Comments

No comment yet. Be the first to post a comment.