| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en"> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Eclipse Platform - Naming Conventions</title> |
| </head> |
| <body> |
| <h1> |
| Eclipse Platform<br> |
| Naming Conventions</h1> |
| <i>Last revised August 15, 2012</i> |
| <p>Naming conventions and guidelines for the Eclipse Platform:</p> |
| <ul> |
| <li> |
| <a href="#Java Packages">Java packages</a></li> |
| |
| <li> |
| <a href="#Classes and Interfaces">Classes and interfaces</a></li> |
| |
| <li> |
| <a href="#Methods">Methods</a></li> |
| |
| <li> |
| <a href="#Variables">Variables</a></li> |
| |
| <li> |
| <a href="#Plug-ins">Plug-ins and extension points</a></li> |
| </ul> |
| |
| <h2> |
| <a NAME="Java Packages"></a><b>Java Packages</b></h2> |
| The Eclipse Platform consists of a collection of Java packages. The package |
| namespace is managed in conformance with <a href="http://www.oracle.com/technetwork/java/codeconventions-135099.html#367">Java's |
| package naming guidelines</a>; subpackages should not be created without |
| prior approval from the owner of the package sub-tree. The packages for |
| the Eclipse platform are all subpackages <b><tt>org.eclipse</tt></b>. The |
| first package name component after <b><tt>org.eclipse</tt></b> is called |
| the <i>major </i>package name. The following major packages of <b><tt>org.eclipse</tt></b> |
| are assigned in the Eclipse 4.3 release: |
| <blockquote><b><tt>org.eclipse.ant[.*]</tt> </b>- Ant support |
| <br><b><tt>org.eclipse.compare[.*]</tt></b> - Compare support |
| <br><b><tt>org.eclipse.core[.*]</tt> </b>- Platform core |
| <br><b><tt>org.eclipse.debug[.*]</tt> </b>- Debug |
| <br><b><tt>org.eclipse.equinox[.*]</tt> </b>- Equinox sub-project |
| <br><b><tt>org.eclipse.help[.*]</tt></b> - Help support |
| <br><b><tt>org.eclipse.jdi[.*]</tt> </b>- Eclipse implementation of Java |
| Debug Interface (JDI) |
| <br><b><tt>org.eclipse.jdt[.*]</tt> </b>- Java development tools |
| <br><b><tt>org.eclipse.jface[.*]</tt> </b>- JFace |
| <br><b><tt>org.eclipse.jsch[.*]</tt> </b>- Jsch SSH library support |
| <br><b><tt>org.eclipse.ltk[.*]</tt> </b>- Generic language tool infrastructure |
| <br><b><tt>org.eclipse.osgi[.*]</tt> </b>- Eclipse API for interacting with OSGi |
| <br><b><tt>org.eclipse.pde[.*]</tt></b> - Plug-in Development Environment |
| <br><b><tt>org.eclipse.search[.*]</tt></b> - Search support |
| <br><b><tt>org.eclipse.swt[.*]</tt> </b>- Standard Widget Toolkit |
| <br><b><tt>org.eclipse.team[.*]</tt> </b>- Team support and Version and |
| Configuration Management |
| <br><b><tt>org.eclipse.text[.*]</tt> </b>- Text editor framework |
| <br><b><tt>org.eclipse.ui[.*]</tt></b> - Workbench |
| <br><b><tt>org.eclipse.update[.*]</tt></b> - Update/install |
| </blockquote> |
| The following package name segments are reserved: |
| <blockquote><b><tt>internal</tt></b> - indicates an internal implementation |
| package that contains no API |
| <br><b><tt>tests</tt></b> - indicates a non-API package that contains only |
| test suites |
| <br><b><tt>examples</tt></b> - indicates a non-API package that contains |
| only examples</blockquote> |
| These name are used as qualifiers, and must only appear following the major |
| package name. For example, |
| <blockquote><b><tt>org.eclipse.core.internal.resources</tt></b> - Correct |
| usage |
| <br><b><tt>org.eclipse.internal.core.resources</tt></b> - Incorrect. <b><tt>internal</tt></b> |
| precedes major package name. |
| <br><b><tt>org.eclipse.core.resources.internal</tt></b> - Incorrect. <b><tt>internal</tt></b> |
| does not immediately follow major package name.</blockquote> |
| <p> |
| Aside on how the Eclipse Platform is structured: The Eclipse Platform is |
| divided up into <i>Core </i>and <i>UI</i>. Anything classified as Core |
| is independent of the window system; applications and plug-ins that depend |
| on the Core and not on the UI can run headless. The distinction between |
| Core and UI does not align with the distinction between API and non-API; |
| both Core and UI contain API. The UI portion of the Eclipse Platform is |
| known as the Workbench. The Workbench is a high-level UI framework for |
| building products with sophisticated UIs built from pluggable components. |
| The Workbench is built atop JFace, SWT, and the Platform Core. SWT (Standard |
| Widget Toolkit) is a low-level, OS-platform-independent means of talking |
| to the native window system. JFace is a mid-level UI framework useful for |
| building complex UI pieces such as property viewers. SWT and JFace are |
| UI by definition. The Java tooling is a Java IDE built atop the workbench. |
| End aside.</p> |
| <p><b>API Packages</b> 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 <b><tt>internal</tt></b>, |
| <b><tt>tests</tt></b>, |
| or <b><tt>examples</tt></b> to avoid confusion with the scheme for naming |
| non-API packages.</p> |
| <p><b>Internal Implementation Packages</b> 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 <b><tt>internal</tt></b>, with the tag occurring |
| just after the major package name. ISVs will be told that all packages |
| marked <b><tt>internal</tt></b> are out of bounds. (A simple text search |
| for "<tt>.internal.</tt>" detects suspicious reference in source files; |
| likewise, "/<tt>internal/</tt>" is suspicious in .class files).</p> |
| <p><b>Test Suite Packages</b> All packages containing test suites |
| should be flagged as <b><tt>tests</tt></b>, with the tag occurring just |
| after the major package name. Fully automated tests are the norm; so, for |
| example, |
| <tt>org.eclipse.core.tests.resources</tt> would contain automated |
| tests for API in <tt>org.eclipse.core.resources</tt>. Interactive tests |
| (ones requiring a hands-on tester) should be flagged with <b><tt>interactive</tt></b> |
| as the <i>last</i> package name segment; so, for example, <tt>org.eclipse.core.tests.resources.interactive</tt> |
| would contain the corresponding interactive tests.</p> |
| <p><b>Examples Packages</b> All packages containing examples that |
| ship to ISVs should be flagged as <b><tt>examples</tt></b>, with the tag |
| occurring just after the major package name. For example, |
| <tt>org.eclipse.swt.examples</tt> |
| would contain examples for how to use the SWT API.</p> |
| <p>Additional rules:</p> |
| <ul> |
| <li> |
| Package names should contain only lowercase ASCII alphanumerics, and avoid |
| underscore <tt>_</tt> or dollar sign <tt>$</tt> characters.</li> |
| </ul> |
| |
| <h2> |
| <a NAME="Classes and Interfaces"></a><b>Classes and Interfaces</b></h2> |
| <p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a> |
| state</p> |
| <blockquote>Class names should be nouns, in mixed case with the first letter |
| of each internal word capitalized. Try to keep your class names simple |
| and descriptive. Use whole words - avoid acronyms and abbreviations (unless |
| the abbreviation is much more widely used than the long form, such as URL |
| or HTML).<br> |
| <br>Examples: |
| <br><tt> class Raster;</tt> |
| <br><tt> class ImageSprite;</tt> <br> |
| <br>Interface names should be capitalized like class names.</blockquote> |
| <p>For interface names, we follow the "I"-for-interface convention: all interface |
| names are prefixed with an "<tt>I</tt>". For example, "<tt>IWorkspace</tt>" |
| or "<tt>IIndex</tt>". This convention aids code readability by making interface |
| names more readily recognizable. (Microsoft COM interfaces subscribe to |
| this convention).</p> |
| <p>Additional rules:</p> |
| <ul> |
| <li> |
| The names of exception classes (subclasses of <tt>Exception</tt>) should |
| follow the common practice of ending in "<tt>Exception</tt>".</li> |
| </ul> |
| |
| <h2> |
| <a NAME="Methods"></a><b>Methods</b></h2> |
| <p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a> |
| state</p> |
| <blockquote>Methods should be verbs, in mixed case with the first letter |
| lowercase, with the first letter of each internal word capitalized.<br> |
| <br>Examples: |
| <br><tt> run();</tt> |
| <br><tt> runFast();</tt> |
| <br><tt> getBackground();</tt></blockquote> |
| Additional rules: |
| <ul> |
| <li> |
| The named of methods should follow common practice for naming getters (<tt>get<i>X</i>()</tt>), |
| setters (<tt>set<i>X</i>()</tt>), and predicates (<tt>is<i>X</i>()</tt>, |
| <tt>has<i>X</i>()</tt>).</li> |
| </ul> |
| |
| <h2> |
| <a NAME="Variables"></a><b>Variables</b></h2> |
| <p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a> |
| state</p> |
| <blockquote>Except for variables, all instance, class, and class constants |
| are in mixed case with a lowercase first letter. Internal words start with |
| capital letters. Variable names should not start with underscore <tt>_</tt> |
| or dollar sign <tt>$ </tt>characters, even though both are allowed.<br> |
| <br>Variable names should be short yet meaningful. The choice of a variable |
| name should be mnemonic - that is, designed to indicate to the casual observer |
| the intent of its use. One-character variable names should be avoided except |
| for temporary "throwaway" variables. Common names for temporary variables |
| are <tt>i</tt>, <tt>j</tt>, <tt>k</tt>, <tt>m</tt>, and <tt>n</tt> for |
| integers; <tt>c</tt>, <tt>d</tt>, and <tt>e</tt> for characters.<br> |
| <br>Examples: |
| <br><tt> int i;</tt> |
| <br><tt> char c;</tt> |
| <br><tt> float myWidth;</tt></blockquote> |
| <p>(Note: we are no longer following the convention that prefixes non-constant |
| field names with "<tt>f</tt>", such as "<tt>fWidget</tt>".)</p> |
| <h2> |
| <a NAME="Constants"></a><b>Constants</b></h2> |
| <p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a> |
| states</p> |
| <blockquote>The names of variables declared class constants and of ANSI |
| constants should be all uppercase with words separated by underscores ("_").<br> |
| <br>Examples: |
| <br><tt> static final int MIN_WIDTH = 4;</tt> |
| <br><tt> static final int MAX_WIDTH = 999;</tt> |
| <br><tt> static final int GET_THE_CPU = 1;</tt></blockquote> |
| |
| <h2> |
| <a NAME="Plug-ins"></a><b>Plug-ins and Extension Points</b></h2> |
| <p>All plug-ins, including the ones that are part of the Eclipse Platform, |
| like the Resources and Workbench plug-ins, must have unique identifiers |
| following the same naming pattern as Java packages. For example, workbench |
| plug-ins are named <b><tt>org.eclipse.ui[.*]</tt></b>.</p> |
| <p>The plug-in namespace is managed hierarchically; do not create plug-in |
| without prior approval from the owner of the enclosing namespace.</p> |
| <p>Extension points that expect multiple extensions should have plural |
| names. For example, "<tt>builders</tt>" rather than "<tt>builder</tt>". |
| </p> |
| </body> |
| </html> |
