Lexical Systems Group - Java Coding Standard Briefing
Contents
- Introduction
- Mandate & Guidelines
- Naming Convention
- File & Class Prolog
- Types of Naming Convention Style
- Accepting a constrained style standard
- Concentrating on the code itself
- Musician example
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
- 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
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
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
- 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
- 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
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
- 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
- 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
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
- 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
- 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
- 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
- LUL_ style should be used
- With such convention, developers are able to distinguish from data members and local variables
- Details
- 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
- 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