NetBeans Code Conventions

All NetBeans Java source code follows the "Code Conventions for the Java Programming Language" as published by Sun. This document is available online at

http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Here we list those rules from the Code Conventions which are most important, plus some programming practices specific to NetBeans

Formatting

• Files longer than 2000 lines are cumbersome and should be avoided.
• Each source file must include the license text in a comment at the very beginning. (XML files may precede this by an XML declaration.)
• Avoid lines longer than 80 characters; long lines often force users to scroll horizontally when they are concentrating on something else (debugging, for example).
• Each top-level class should be kept in a separate file. (It is fine to use nested classes, though generally discouraged when visible in an API.)
• When wrapping code lines, break after a comma or before an operator.
• Four spaces should be used as the unit of indentation. Tabs should be avoided and if are used then must be set exactly every 8 spaces.
• An open brace { appears at the end of the same line that begins the statement.
• A closing brace } starts a line by itself indented to match its corresponding opening statement. However null statements may be written as {} on one line.
• A blank space should appear after commas in argument lists.
• All binary operators except . (dot) should be separated from their operands by spaces. Blank spaces should never separate unary operators from their operands.

Programming Practices

• Public classes and interfaces as well as public or protected methods and fields must have documentation comments. See

  "How to Write Doc Comments for Javadoc"
  http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

  for details on writing good doc comments. However if a method simply overrides a superclass method, and does not add any contractually significant behavior to it beyond what is obvious from the class Javadoc, then the documentation comment should be omitted - since JDK 1.3, the javadoc tool will automatically copy the documentation from the superclass, which is more maintainable.
• All class and instance variables should be private except for constants that are declared as static final.
• Throwing an unchecked exception without mentioning it in the Javadoc is forbidden. IllegalStateException or JDK 1.4 assertions may be used when the code is in an inconsistent state that it should be impossible to enter.
• If a method accepts null as an argument value, say so in the method Javadocl otherwise callers must not pass null to method calls.
• If a method returns null, document its meaning in the Javadoc; otherwise it is safe for callers to assume the return value is not null.
• Unless otherwise specified, all arrays passed into or out of methods or constructors are assumed to be immutable, i.e. the contents of the array must be fixed when it is constructed and never changed by any party afterwards. Similarly, all collections (List, etc.) are assumed to be immutable unless otherwise specified in the Javadoc comments. To be sure, Javadoc ought to explicitly qualify descriptions of array and collection parameters and return values as "mutable" or "immutable". When they are mutable, some indication should be given of who is permitted to mutate the array or collection (e.g. creator of object only, receiver only, any party), and when (e.g. required thread, lock, or mutex).
• All fields, parameters, and return values of collection types (e.g. Map or Enumeration) must specify what the intended element type is, as if generics were in use. For code readability and ease of future transition to 1.5 source, the source code should put generic markings in comments, for example:

  private final Map/*<String,List<String>>*/ stuff = new HashMap();
  

• If an exception is caught and ignored, there must be comments saying why; if in doubt, notify with ErrorManager at INFORMATIONAL level.
• Catch Exception only when a checked exception might be thrown; if only unchecked exceptions are possible, catch RuntimeException.
• If a Throwable is caught the handling code must check whether it is an instance of ThreadDeath and in this case rethrow it, unless it is expected that the thread might be stopped (e.g. an executed subprocess). Generally catching Error or Throwable should be considered carefully, as conditions such as OutOfMemoryError are not usually recoverable. Code loading or deserializing foreign classes may catch LinkageError in addition to Exception to handle problematic code.
• Never throw a subclass of Error (unless rethrowing). In case your method is called from an inappropriate place, or internal data structures are in an inconsistent state and further processing would only compound the problem, throw IllegalStateException; use ErrorManager to annotate localized messages or other throwables as needed.
• String literals which are not intended to be localized should be marked by putting a comment containing NOI18N in the same line. See Internationalization, Localization, and Branding of NetBeans for details.
• Careful with string.toUpperCase() and string.toLowerCase(). In Turkish locale, I and i are not case variants, they are different letters. Unless you know what you are doing, use string.toUpperCase(Locale.US) or string.toLowerCase(Locale.US).
• Be friendly to the version control system: Do not reformat code without semantic/syntactic changes, even in case existing code breaks formatting conventions.
• Prefer explicit imports to wildcards for clarity; if using NetBeans to edit code, the Fix Imports command makes it easy to maintain them. Keep imports sorted.

Code Example

/*
/* The contents of this file are subject to the terms of the Common 
Development and Distribution License (the License). You may not use this 
file except in compliance with the License.  You can obtain a copy of the 
License at http://www.netbeans.org/cddl.html

When distributing Covered Code, include this CDDL Header Notice in each
file and include the License. If applicable, add the following below the
CDDL Header, with the fields enclosed by brackets [] replaced by your own
identifying information:
"Portions Copyrighted [year] [name of copyright owner]"

Copyright 2005 Sun Microsystems Inc. All Rights Reserved
*/


package org.netbeans.modules.nosuchpackage;

import java.util.ArrayList;
import java.util.List;
import org.openide.nodes.Node;

/**
 * This is a totally useless class with a summary sentence ending with a period.
 * Its only purpose is to demonstrate the NetBeans code conventions.
 */
public class NoSuchClass extends SomeClass {

    /** the default capacity */
    public static final int DEFAULT_CAPACITY = 32;

    /** the objects being stored, of type <code>NoSuchElement</code> */
    private final List/*<NoSuchElement>*/ storage = new ArrayList(50);

    /**
     * Creates a new instance of <code>NoSuchClass</code> with default capacity.
     */
    public NoSuchClass() {
        this(DEFAULT_CAPACITY);
    }

    /**
     * Creates a new instance of <code>NoSuchClass</code> with a given capacity.
     * @param capacity number of slots to be preallocated
     */
    public NoSuchClass(int capacity) {
        // ... implementation goes here
    }

    /**
     * Finds an entry with a given name.
     * @param name name to look for
     * @return an entry with a specified name or <code>null</code> if
     *         no such entry is found
     */
    public Entry findEntry(String name) {
        // ... boring code deleted ...

        if ("nef".equals(name)) { // NOI18N, backdoor :-)
            // ...
        } else {
            // ...
        }

        // ... boring code deleted ...
    }
}

---

Edited by Trung Duc Tran < > and Jesse Glick < >
July 14, 2005