Downloaded from http://developer.netscape.com/docs/technote/java/codestyle.html.

NETSCAPE'S SOFTWARE CODING STANDARDS GUIDE FOR JAVA

Christie Badeaux, Technology Evangelist

INTRODUCTION

In August 1997, Marc Andreesen announced that Netscape would be releasing a 100% Pure Java Navigator in 1998.  At that time the client product engineers were already well into coding applications with Java.  Along the way, the engineers had created a set of Java coding guidelines to be used in creating this next generation Communicator product.  What follows is a subset of those guidelines that I thought you might be interested in using for your own Java development.


GOALS OF THESE STANDARDS

First of all there is the need to recognize the purpose of these guidelines and set some goals.  Following are three basic, but very important goals:

In order to write great software, you have to write software greatly. Vague? Well, the point is that before you can produce great code, you have to have developed a process for writing great code. And that is what these standards are intended to help with.

Some amount of standardization is especially important in a large development organization writing component software.  Everybody will be in everybody else's code, and that code must be clear.  It must be clear what the code does, how it should be used, how it can be extended, etc.  The standards within this document have been written to balance the group need for standardization with the individual's desires to code in the ways they feel most efficient.
 

SCOPE AND APPLICATION OF THESE STANDARDS

It is very important to note that this document is divided into two distinct areas -- Rules and Guidelines. It is very important to recognize the following....

OVERVIEW OF THE DEVELOPMENT DOCUMENTATION

  • General Coding Rules
  • Naming Conventions
  • Commenting Code
  • General Coding Guidelines
  • Source Code Style Guidelines
  • Naming Guidelines
  • Layout of Source (.java) Files
  • Documentation for Methods and Functions
  •  

    GENERAL CODING RULES

    Rules are those coding standards that are "necessary and required" coding practices that have been agreed upon by members of the Java Communicator team. Everyone is expected to follow these "rules".
     

    NAMING CONVENTIONS

    COMPONENT FACTORY NAMES

    A component factory is a public class that implements only static methods. These static methods are "Factory functions" or "component constructors".  Factory class names should include the word "Factory".  Factory method names should start with the word "Make."  For example,

     

    COMMENTING CODE

    All interfaces and public classes should have JavaDoc comments. See the JavaDoc documentation available from JavaSoft.


    GENERAL CODING GUIDELINES

    Guidelines are "suggested" coding practices that have been written to recognize the need for individuality AND for common coding practices. The purpose of the guidelines is to provide a framework upon which we can all create better code.  However, the guidelines are not meant to impede engineering efforts when these guidelines are found to be in direct conflict with an individual's preference, so long as that preference is implemented consistently and is well documented. Finally, because we recognize that this opens the code upon to individual stylist coding habits, it is important that these habits are well documented and will then become the basis for all other updates within the affected files, i.e. when in someone else's code do as they do.
     

    JAVA GRAMMAR

    PARENTHESES CONSTANTS   "MAGIC" NUMBERS

    DEBUGGING

    1. First and foremost, understand how to write solid code. Then go back and reread the java programming language reference documentation from JavaSoft to refresh you memory on the precedence order of operators.
    2. Now go read the internal document on abnormal condition handling.
    3. Make sure every path of execution through your code has been thoroughly tested. You can never do enough coverage testing. Here's a neat idea: try actually stepping through each line! While you're hard at work testing your code, be sure to throw invalid inputs at every public interface you provide. The last thing we want to do is crash because your routine didn't handle invalid inputs from ours. Never ever break the build.
    4. Want to know the secret to fast code? Calculate those comparison values once: reuse them often. Avoid global variables too, since they can wreak havoc with the pre-fetch instruction queue.
    5. Don't forget to adhere to our Orthodox Canonical Form. This is a template that, when followed, guarantees that you have all the default methods your class needs to be a good java citizen. It is our policy to produce code that can test itself to the greatest extent possible. To that end, we encourage the use of three debugging techniques: asserts, pre/post conditions and self testing methods.
      

    SOURCE CODE STYLE GUIDELINES

    LINE SPACING

    BRACES  
    IF / ELSE examples:  
    if (expression)
    {
      statement;
    }
    else
    {
      statement;
    }
    or
    if (expression) {
      statement;
    } else {
      statement;
    }

     

    WHILE examples:  
    while (expression)
    {
      statement;
    }
    or
    while (expression) {
      statement;
    }
    DO..WHILE
    do {
      statement;
    } while (expression);

    or

    do {
      statement;
    } while (expression);

     

    SWITCH TRY/CATCH/FINALLY

    NAMING GUIDELINES

    GENERAL
    All type declarations should follow standard java package naming.

    MEMBER DATA NAMES
    public class CxMyClass {
        public void setMyOrdinalValue(int aValue);
        public int getMyOrdinalValue();
        private int fMyOrdinalValue;
    };
    PARAMETER NAMES example  
    public boolean numberIsEven(int aValue, Object anObject)  {
      ...
    }
     

    LAYOUT OF SOURCE FILES (*.java)

    The layout for a class will be broken up into the following main sections: Copyright NoticeFile Description; Package Name, Imports, Constants, Methods, protected and private members. Each section will be prefaced by an appropriate header block defining the section.

    COPYRIGHT NOTICE

    This will be the standard "legalese" copyright notice.

    /* Copyright Notice =====================================*
     * This file contains proprietary information of Netscape Communications.
     * Copying or reproduction without prior written approval is prohibited.
     * Copyright (c) 1997 =====================================* /

    FILE DESCRIPTION
    This is a brief description of what the file is, does and represents. It should describe the overview of how to use the file (or classes therein). JavaDoc compatible commenting style is required. See the JavaDoc documentation available from JavaSoft.

    PACKAGE NAME

    Package names should occur on the first non-commented line of the source file and should following the naming conventions defined in this document.

    IMPORTS

    Immediately following the package name should be the imported class names.

    CONSTANTS

    See the naming conventions defined in this document.

    METHOD DECLARATIONS

    Each method is preceded by a description in JavaDoc format. Public methods MUST have a standard javadoc comment header.  These must be professionally commented.  Remember, you never know what code will eventually be made public outside of Netscape.

    Standard access methods may be grouped without a description (access methods assign or return an object attribute). Optionally, methods may be grouped within logical groupings. Here are some suggestions...
     

    example
     
    CLASS DEFINITIONS
    This section is the actual implementation of the class. Each method (and private function) will be prefaced by the standard documentation header. Read the Documentation for Methods and Functions defined in this document.


    DOCUMENTATION FOR METHODS AND FUNCTIONS

    The following standard has been established for the documentation of methods and functions. Optional items are to be included only where applicable. A complete description of each section in the routine documentation follows.

    The header is designed to be easy to use. Many items are optional, and may be omitted where they are not applicable. Each line item begins with an asterisk, and ends with blank space. You do not place an asterisk next to each line in a multiline component, only the topmost, next to the title. All subsequent lines in multiline component are to be indented so that they line up vertically with the previous line.
     

    DESCRIPTION PARMS SECTION RETURNS SECTION EXCEPTION SECTION           * @exception ResourceNotFoundException. recoverable, try another resource
     

    For more Internet development resources, try Netscape TechSearch

    DevEdge Online FAQ
    Developer Response Center
    Join DevEdge Program
    Copyright © 1999 Netscape Communications Corporation.
    This site powered by: Netscape Enterprise Server and Netscape Compass Server.