Because of a lapse in government funding, the information on this website may not be up to date, transactions submitted via the website may not be processed, and the agency may not be able to respond to inquiries until appropriations are enacted. The NIH Clinical Center (the research hospital of NIH) is open. For more details about its operating status, please visit cc.nih.gov. Updates regarding government operating status and resumption of normal operations can be found at OPM.gov.

Text Categorization

Lexical Systems Group - Java Coding Standard Briefing


Contents

  1. Introduction
  2. Mandate & Guidelines
  3. Naming Convention
  4. File & Class Prolog
  5. Types of Naming Convention Style

Introduction

  • Accepting a constrained style standard
  • Concentrating on the code itself
  • Musician example

Rational

A primary aim of writing code is to make its meaning clear to the next person reading it - and that person just might be yourself a few years hence (Stroustrup).

  • Follow a clear and consistent style/standard so that your code is easier to read, understand, and maintain.
  • Writing clear and clean codes is professional, don't mistakenly think of is as job security.
  • Getting group agreement on a coding style/standard is never easy. Professionals have to do what is best for the team, rather than what we individually prefer.

  • Details

Scope

  • Deliverable codes - mandatory & guideline
  • Non-deliverable codes - highly recommanded
  • Code that does not conform to this standard shall not be reviewed, released, and distributed.

  • Details

CodeLayout

The layout of code on the page shall reflect the structure of the code. Code layout should be seen the same in different computers by different viewers.

  • Layout should be clear and easy to read.
  • Indentation: always use spaces to indent (use 4 sapces as an indentation level).
  • Don't use indentation deeper than 4 levels.
  • Use a fixed-width font (like Courier) and never use a proportional-width font.
  • Don't put multiple statments on a single line.
  • Use 79 ncharacters or less for the length of a cousrce line.
  • Order declarations with initalized variables first.
  • Align variable names, "=" signs, and values in columns.

  • Details

Comments

The importance of comments can not be emphasized enough.

  • Make sure comments and code agree.
  • Make every comment count (don't jsut echo the code with comments).
  • Don't comment bad code - rewrite it.
  • Use "// ..." commenting style in Java.
  • Use class prolog samples.

  • Details

Declarations

  • Variables
    • Decleare vairables where they are needed
    • Use keyword final for constant variables
    • Each vaiable must be declared upon a seperate line
  • Methods
    • Explicit prototype: return value type, parameter types, and meaningful parameter names.
    • Use private access for a method is local to a single source file.
  • Classes
    • Put the public declaration first
    • In general, one class per implementatin file


  • Details

Flow Control

  • Always provide a break or return statement for each case in a switch statment.
  • Always provide a default case in a switch statment.
  • Always expect at least one of the if condition to be true in a sequence of "if ... else if ... else" statement
  • Always use braces "{ }" to delimit compound statment
  • Alwyas use parentheses to clarify the order of complex expressions

  • Details

Naming Convention: General

Everything that has a name shall have a meaningful name.

  • Leading underscores "_" shall not be used
  • Name must begin with a letter.
  • All naming conventions are mandatory
  • Name must be 31 alphanumeric or underscore characters or less

  • Details

Naming Convention: Directories

  • The name of an directory shall accurately reflect the catagory of its contained files
  • The distribution of directories should be mapped into the software architecture design
  • UL style should be used

  • Details

Naming Convention: Packages

  • The name of an Java package shall accurately reflect the chracteristics of its catagory
  • In general, the name of a Java package should be the same as the name of its directory
  • UL style should be used

  • Details

Naming Convention: Files

The format for Java source file name is: < ClassName > . < extension >

  • ClassName is the same as the name of the first class contained in the file
  • The name of an implementation Java file shall accurately reflect the contents of the file.
  • UL style should be used
  • Extension is "java"

  • Details

Naming Convention: Classes

  • UL style should be used
  • A good convention is that a class name should be
    • A nour: Order
    • A noun preceded by adjective: RushOrder
    • A gerund: BillingAddress


  • Details

Naming Convention: Methods

  • UL style should be used
  • The return type pf each method must be explicitly defined.
  • With such convention, developers are able to distiguish methods form users defined and Java's

  • Details

Naming Convention: Variables & Parameters

  • LUL style should be used
  • The size of every array shall be given as a named constant.
  • Global vaiables should not be used as a guideline for OO design.

  • Details

Naming Convention: Data Members

  • LUL_ style should be used
  • With such convention, developers are able to distinguish from data members and local variables

  • Details

Naming Convention: Constants

  • UU style (all capitals) should be used
  • Constant may be implemented by using keyword "final"
  • Exceptions:
    • -1 and 1 to increment and decrement loop counters
    • 0 (zero)
    • string constant, scuh as "\n", "\t", etc.


  • Details

File (Class) Prolog


Naming Convention Style

  • UU: used in constant names (MAGIC_NUMBER)
  • LL: not used
  • UL: used for directory name, Java package name, file name, class name, and method name (MyDirectory, MyPackage, MyFile, MyClass, MyMethod).
  • LUL: used in vairables and parameters names (localVariable)
  • LUL_: used in data members (dataMember_)

  • Details