Code conventions

Intended for WiTrack developers

WiTrack Team

4/27/2007

Introduction

Why Have Code Conventions?

Code conventions are important to programmers for a number of reasons:

• 80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
• If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

Acknowledgments

Most of these rules are from the Code Conventions for the Java Programming Language (http://java.sun.com/docs/codeconv/) and from the Epitech norm of code.

Naming conventions

Packages

The prefix of a unique package is net.witrack

Subsequent components of the package name vary according to the project name or components.

Examples:

Classes

Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).

Examples:

==

Interface names should be capitalized like class names.

Examples:

Methods

Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.

Examples:

Variables

Except for variables, all instance, class, and class constants are in mixed case with a lowercase first letter. Internal words start with capital letters.

Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.

Examples:

Class variables

Class variables should not have any prefix and must be referenced using the this object.

Example:

   private String someString;

   public void someMethod()

   {

       logger.debug("Value = " + this.someString);

   }

Constants

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

Examples:

License

Each source file has to start with the following notice:

Placement of spaces and braces

Spaces:

·after commas,

·after semicolons

·in for statements,

·before and after operators, +, =, <=, etc.,(but not before and after the . operator.)

·before (,

·after )

Example:

   n++;

No space between the function name and (.

Example:

Braces:

All braces should begin and end on a new line.

Example:

     return (cp);

Brackets are mandatory even for single line statements !

   // some code

   // some code

Indentation

Line Length

Avoid lines longer than 80 characters, since they're not handled well by many terminals and tools.

Wrapping Lines

When an expression will not fit on a single line, break it according to these general principles:

·Break after a comma.

·Break before an operator.

Examples:

       longExpression4, longExpression5);

          + 4 * longname6;

Blank lines

Blank lines improve readability by setting off sections of code that are logically related.

Two blank lines should always be used in the following circumstances:

·Between sections of a source file

·Between class and interface definitions

One blank line should always be used in the following circumstances:

·Between methods

·Between the local variables in a method and its first statement

Comments

Comments should not describe program implementation.They should describe what is done, the purpose, not how it is done. Comments should not just repeat the program code.

Javadoc

Each class and method SHOULD be preceded by a ‘Javadoc’ comment describing the purpose of the class or method. Also, if you are working on existing code and there currently isn't a

Javadoc for that method/class/variable or whatever, then you should contribute and add it.

This will improve the project as a whole.

Also add code comments when you think it's necessary (to explain any tricky logic), especially when the code is not obvious.

Examples:

* Student is the class which allow to manage students 

* @version 2.6

*/

public class Student

{

  ...

}

* Validates a chess move.

* 

* @param theFromFile File of piece being moved

* @param theFromRank Rank of piece being moved

* @return            true if a valid chess move or false if invalid

boolean isValidMove(int theFromFile, int theFromRank, 

{

    ...  

}

Javadoc author references

Do not put @author tags in source code.

This view is summarized nicely by Dirk-Willem Van Gullick, president of the ASF.

Exception handling

Managing exceptions correctly requires experience. This is not supposed to be a guide on managing exceptions, simply a few best practices.

·Try to catch exceptions as much as possible and rethrow higher level exceptions (meaning hiding the low level detailed and putting a message that is more related to the function of your code).

·It is important not to loose the stack trace which contains important information. Use chained exceptions for that.

·Always log the exception at the higher level (i.e. where it is handled and not rethrown).

·Try to avoid catching Throwable or Exception and catch specific exceptions instead.

Example:

   try

   {

       Class responseClass =

           Class.forName("some.package.MyClass");

   } 

   catch (ClassNotFoundException cnfe)

   {

       String message = "Cannot instantiate test class";

       logger.error(message);

       throw new ChainedRuntimeException(message, e);

   }

Qualified imports

All import statements should contain the full class name of classes to import and should not use the "*" notation.

Example:

</div>