Conventions and Guidelines

As with any product being built by a team, there are various areas where standards, conventions, and other guidelines can play a role in helping to ensure that the resulting product presents to developers and customers as a unified whole rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working.

Sun has established coding standards that are generally considered reasonable, as evidenced by their widespread adoption by other Java-based development efforts.

Sun's Code Conventions for the Java Programming Language covers filenames, file organization, indentation, comments, declarations, statements, white space, naming conventions, and programming practices. All code written for the SolarEclipse project should follow these conventions except as noted below. We deviate from Sun guidelines only in places where our needs differ from Sun's. (The section numbers shown below are Sun's.)

Section 3.1.1 Beginning Comments
The SolarEclipse project has specific guidelines for copyright notices to appear at the beginning of source files (see bellow).

Section 3.1.2 Package and Import Statements
The SolarEclipse project has specific guidelines for order of import statements (see bellow).

Section 4 Indentation
Only tabs must be used for indentation (Eclipse default). Tabs should be set exactly every 4 spaces (not 8). Only spaces should be used for other alignment (inside comments etc.).

Section 9 Naming Conventions
The SolarEclipse project has more specific naming conventions (see bellow).

Beginning Comments

All contributions to the SolarEclipse project must adhere to the Common Public License Version 1.0. Notwithstanding the above, SolarEclipse Project downloads may include separately licensed code from third parties as a convenience and where permitted by the third party license, provided this is clearly indicated.

All contributions must contain the following copyright notice.

/**********************************************************************
Copyright (c) {date} {name of original contributor} and others.
All rights reserved.   This program and the accompanying materials
are made available under the terms of the Common Public License v1.0
which accompanies this distribution, and is available at
http://solareclipse.sourceforge.net/legal/cpl-v10.html

Contributors:
    <contributor1> - <description of contribution>
    <contributor2> - <description of contribution>
    ...
**********************************************************************/

The original contributor is the one who contributes the first version of the file. A contributor may be a person or an organization - whoever owns the copyright. If the contributor is an organization, the person may also be indicated. For each additional contributor, indicate the part of the code or contribution that came from the contributor, especially if it contains an interesting algorithm or data table etc. For clarity, also indicate the contributor in the actual section of contributed code. Also reference the bug ID if applicable. The basic principle is to clearly identify the contribution... especially if it is a separable block of code.

Import Statements

Order of imported packages should be set to following:

net.sf.solareclipse[.*] - SolarEclipse packages
org.eclipse[.*] - Eclipse packages
com[.*] - Some libraries
net[.*] - Some libraries
org[.*] - Apache, W3C, etc. libraries
javax[.*] - SUN APIs (Extensions)
java[.*] - SUN APIs

This way most specific libraries imported at the top close to package definition, whenewer most common APIs imported last.

Indentation

Only tabs must be used for indentation. Tabs should be set exactly every 4 spaces (Eclipse default), not 8 (Sun's conventions). Only spaces must be used for any other alignment (inside comments etc.).

Naming Conventions

Like other open source projects, the code base for the SolarEclipse project should avoid using names that reference a particular company or their commercial products.

Workspace Projects

The name of the SolarEclipse workspace project should match the name of the plug-in. For example, net.sf.solareclipse.xml.core plug-in is developed in an Eclipse workspace project named net.sf.solareclipse.xml.core.

Java Packages

The SolarEclipse project consists of a collection of Java packages. The package namespace is managed in conformance with Sun's package naming guidelines; subpackages should not be created without prior approval from the owner of the package subtree. The packages for the open-source SolarEclipse project are all subpackages net.sf.solareclipse.

The first package name segment after net.sf.solareclipse is generally the subproject name, followed by the component name.

net.sf.solareclipse.<subproject>.<component>[.*] - General form of package names
The following package name segments are reserved:
internal - indicates an internal implementation package that contains no API
tests - indicates a non-API package that contains only test suites
examples - indicates a non-API package that contains only examples

These name are used as qualifiers and appear between the subproject and component name.

API Packages  API packages are ones that contain classes and interfaces that must be made available to ISVs. The names of API packages need to make sense to the ISV. The number of different packages that the ISV needs to remember should be small, since a profusion of API packages can make it difficult for ISVs to know which packages they need to import. Within an API package, all public classes and interfaces are considered API. The names of API packages should not contain internal, tests, or examples to avoid confusion with the scheme for naming non-API packages.

Internal Implementation Packages  All packages that are part of the platform implementation but contain no API that should be exposed to ISVs are considered internal implementation packages. All implementation packages should be flagged as internal, with the tag occurring just after the major package name. ISVs will be told that all packages marked internal are out of bounds. (A simple text search for ".internal." detects suspicious reference in source files; likewise, "/internal/" is suspicious in .class files).

Test Suite Packages  All packages containing test suites should be flagged as tests, with the tag occurring just after the major package name. Fully automated tests are the norm; so, for example, net.sf.solareclipse.xml.tests.resources would contain automated tests for API in net.sf.solareclipse.xml.resources. Interactive tests (ones requiring a hands-on tester) should be flagged with interactive as the last package name segment; so, for example, net.sf.solareclipse.xml.tests.resources.interactive would contain the corresponding interactive tests.

Examples Packages  All packages containing examples that ship to ISVs should be flagged as examples, with the tag occurring just after the major package name. For example, net.sf.solareclipse.xml.examples would contain examples for how to use the XML Development Tools API.

Additional rules:

  • Package names should contain only lowercase ASCII alphanumerics, and avoid underscore _ or dollar sign $ characters.

Classes and Interfaces

For interface names, we follow the "I"-for-interface convention: all interface names are prefixed with an "I". For example, "IWorkspace" or "IIndex". This convention aids code readability by making interface names more readily recognizable...

Plug-ins and Extension Points

All plug-ins (and plug-in fragments) must have unique identifiers following the same style of naming convention as Java packages.

Extension points that expect multiple extensions should have plural names. For example, "builders" rather than "builder".