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 Section 3.1.2 Package and Import Statements Section 4 Indentation Section 9 Naming Conventions |
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 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 namesThe following package name segments are reserved: internal - indicates an internal implementation package that contains no API 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:
|
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, |