ChiMu  Publications  Java Development Standards

Previous TOC Next

Source code format

Sectioning

The following describes the general sectioning of interface and class files. There are also method categories within these major sections, and these are visible in source files but not in the JavaDoc API. Because classes are encapsulated within interfaces and "packs", the sectioning of a class file is only important for the class developer or maintainer and should be organized to help that person.

Section ordering for Interfaces

• Constants
• Methods

Section Ordering for Classes

Subsectioning

Within each section are method categories that organize the methods of that section. These are equivalent to Eiffel features labels (without the export control) or Smalltalk protocols/method-categories (without having a nice browser). A category normally ends with ‘ing’. Categories can have subcategories that organize on a more refined level. Categorizing is designed to make a class or interface file more organized and readable, so you should try to stay in the happy middle between too few categories (e.g. none) and too many sections (e.g. one per method)

The following is an ordered list of categories and definitions:

The following is an example of sectioning in code. This would look a bit more balanced if the method bodies were included.

    //**********************************************************
    //(P)********************* Copying *************************
    //**********************************************************
    
    public Object copy() {..}
    protected void initFrom(CompanyClass company) {..}
    
    //**********************************************************
    //(P)****************** Displaying *************************
    //**********************************************************
    
    public String toString() {...}
    public String info() {..}
    
    //**********************************************************
    //(P)********************* Asking **************************
    //**********************************************************
    
    public String name() {..}
    public int revenue() {..}
    
    //**********************************************************
    //(P)******************** Creating *************************
    //**********************************************************
    
    public Project newProject(String name, Date startDate) {..}
    
    //**********************************************************
    //(P)******************** Altering *************************
    //**********************************************************
    
    public void setName(String name) {..}
    public void setRevenue(int revenue) ..}

Comments

I place the JavaDoc comments immediately above and inset relative to the method declaration. This is so it is easy to read the method declaration before reading the comment. A method should have a good, intention revealing selector, good parameter names, and a suitable return value type. This implies that the declaration itself is the best first source for documentation of the public use of the method.

       /**
        * Prepare the query so that its unbound variables can
        * be bound
        */
    public void prepareForBinding() {

In effect, I consider the comment to be inside and subservient to the declaration, but JavaDoc requires it to be before the declaration.

Because I try to have communicative method names and standard patterns for categories of method, I will frequently leave off method comments. I never repeat the information that can be found simply by reading the declaration.

I do not indent Class comments. Class comments have enough information that they are not optional on released software.

Interfaces and comments

Interfaces are where the public protocols of a system are defined, so they provide the main documentation. Documentation is not repeated in a class for the methods that are defined in an interface. Only implementation documentation will be in a class.

Keyword Order

Since I consider static methods to be a completely different kind of method (they are actually statically bound functions and procedures), this is the first qualifier mentioned. After this comes the access control (including the comment specifying more specific access than Java currently provides). This is followed by all the not-elsewhere-mentioned qualifiers. Finally we have the type specification.

1. [‘static’]
2. ‘public’ | ‘/*subsystem*/ public’ | ‘/*package*/ public’ | ‘/*package*/’ | ‘/*progeny*/’ | ‘protected’ | ‘private’
3. [‘abstract’], [‘synchronized’], [‘final’], [‘native’], [‘transient’], [‘volatile’]
4. ‘void’ | <TypeName>

	ChiMu  Publications  Java Development Standards	Previous TOC Next
	Copyright (c) 1997, Mark L. Fussell.

mirror of page http://www.chimu.com/publications/javaStandards/part0007.html