Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part III

Coding Standard for BDE2JAVA
1.0

These are the coding standards for usage in bde2java project development. They were derived by mutual consent and discussion by the bde2java team, 96f523.

1. Variables:

All variables are as defined in standard Java definition.

All variables must have descriptive names.

All variables need brief inline descriptive comments.

---

1.1 External public variables

Usage of these variables require explicit statement of their path (their root locations) either as a part of the expression or as comments.

1.2 Local variables

All local variables are to be defined at the top of the class or method block in which they are defined.

1.3 Declaration Grouping

All the variables are declared at the top of their class or method blocks and should be grouped in the following order:

1^st) Variable declaration and declaration with simple assignment.

Variable declaration consists of expression containing type and variable name.Variable declaration with simple assignment consists of simple declaration followed by assignment expression were the right hand value consists of a constant value.

2^nd) Variable declarations with complex assignments.

Variable declaration with complex assignment consists of an assignment were the right hand value is a method call or a compound expression.

Variable ordering within groups left to programmer's discretion.

2. Constants:

All constant names should be capitalized.

3. Naming Conventions:

The following conventions apply to all naming situations unless otherwise specified or superseded by specific conventions defined in type description (i.e. Constants, Variables).

Abbreviations should be avoided whenever possible. It is recommended that some abbreviations be referenced from a table of standard abbreviations to maintain variable naming consistency when abbreviations are used.

Names should be descriptive of functional purpose.

All class naming must be preceded by the word "bde" in lower case. The first letter after "bde" should be capitalized. If the name is composed of multiple words, each first letter is respectively capitalized.

4. Code Documentation Conventions:

Code documentation refers to commentary to be contained within the code itself as both inline comments and as part of the javadoc build comments. This not a specification for other types of documentation (final reports, user guides, etc.).

4.1 In General

Comments must address the following:

• All closing brackets for ending classes and methods should be labeled
• All non-trivial block closing brackets (branches and loops, eg. ends if | ends while) should be described.
• All branching statements (eg. If and case switches) should be described
• Non-trivial control loops should be commented as purpose of block and in the case of while loops, reason for break. Note that due to this last aspect, no while loops are considered trivial.
• All classes and methods are to be preceeded by a comment block clearly demarcated from the rest of the code. The design of the block should be consistent with javadoc build requirements (see below)
• All class definitions should have their class variables as well as class children commented.

4.2 Javadoc Specific

All code is to contain code that will allow java doc builds consistent with current java doc style as per jdk sources. These are opened by using the /** tag closed by */. Within the enclosed javadoc comment, the comment may contain additional control tags. The reader may refer to the document /usr/u/fac1/lechner/public_html/bde2java /javadocDev.shtml (Ref. Guide part IV) - the javadoc tutorial section - for further reference. Non-javadoc inline comments are distinguished by the use of // and /* ... */ as comment tags.

• The header comment block is the main means of placing information intended for javadoc. As a result design for the header block is the following.

       /* *************************************/
       /**
       *     contents
       *     
       */
       /* *************************************/

This is intended to allow a clearly demarcated block, but should not result in formatting errors.

• All classes should incluse their class name and a concise description of the domain of their methods.
• Methods should include their names, concise description, State variables Class description, parameter list information (@param), return values (@return) and exceptions (@exception). Description should include pre/post conditions and side effects if any.

5. Coding Conventions:

All class and method definitions will contain the necessary javadoc build comments compatible with current java style documentation for java doc (as per previous section).

Standard indentation rules denoting bracket nesting should be practiced. The programmer should make an effort, however, to try to maintain the code to within 80 columns due to the difficulty in generating wide margin output.

Only one class should be defined per file. Files will need to be maintained in the file hierarchy as required by the java environment.

Code examples follow.

5.1 Header Block Example:

For Class description

/* ****************************************************************/
/**
*
*       Class: Class name 
*
*       Description: Text Description (per commenting requirements)
*/
/* *****************************************************************/

subsequent code...

For Method description (note slight indent)

   /* ****************************************************************/
   /**
   *
   *       Method:(public|private)(return value)(Method name)(parameter list)
   *
   *       Description: Text Description in full 
   *                    - pre & post conditions 
   *                    -side effects
   *
   *       State: any key state (control) variables
   *
   *       Class: Encapsulating Class name
   *
   *       @param parameter details
   *       @returnreturn values
   *       @exception error exception breaks
   */
   /* *****************************************************************/

subsequent code...

Consult the javadoc Development Report(Ref. Guide part IV) listed in section 4.2 for additional support and examples of the results from a properly formatted javadoc comment. [an error occurred while processing this directive]