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