Naming Conventions

Naming Conventions From Eclipsepedia Contents • General o 1.1 Eclipse Workspace Projects o 1.2 Java Packages o 1.3 API Packages o 1.4 Internal Implementation Packages o 1.5 Test Suite Packages o 1.6 Examples Packages o 1.7 Additional rules • Classes and Interfaces • Methods • Variables • Constants • Plug-ins and Extension Points • System Files and Settings General Like other open source projects, the code base for the Eclipse project should avoid using names that reference a particular company or their commercial products Eclipse Workspace Projects When Eclipse is being used to develop plug-ins for the Eclipse project, the name of the Eclipse workspace project should match the name of the plug-in For example, org.eclipse.core.runtime plug-in is developed in an Eclipse workspace project named org.eclipse.core.runtime Java Packages The Eclipse Platform 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 Eclipse project are all subpackages org.eclipse The first package name segment after org.eclipse is generally the subproject name, followed by the component name org.eclipse..[.*]- General form of package names The following subprojects are assigned at the time of writing: org.eclipse.jdt.[.*] - Java development tooling org.eclipse.pde.[.*] - Plug-in development environment 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: org.eclipse..internal.[.*] - internal package org.eclipse..tests.[.*] - tests org.eclipse..examples.[.*] - examples In the case of the Eclipse Platform proper, there is no subproject name, and the qualifiers appear immediately after the component name: org.eclipse.[.*] - Eclipse Platform proper org.eclipse..internal[.*] - Eclipse Platform internal package org.eclipse..tests[.*] - Eclipse Platform tests org.eclipse..examples[.*] - Eclipse Platform examples The following components of the Eclipse Platform proper are assigned at the time of writing: org.eclipse.ant[.*] - Ant support org.eclipse.compare[.*] - Compare support org.eclipse.core[.*] - Platform core org.eclipse.debug[.*] - Debug org.eclipse.help[.*] - Help support org.eclipse.jdi[.*] - Eclipse implementation of Java Debug Interface (JDI) org.eclipse.jface[.*] - JFace org.eclipse.platform[.*] - Documentation org.eclipse.scripting[.*] - Scripting support org.eclipse.sdk[.*] - SDK configuration org.eclipse.search[.*] - Search support org.eclipse.swt[.*] - Standard Widget Toolkit org.eclipse.ui[.*] - Workbench org.eclipse.update[.*] - Plug-in live update org.eclipse.vcm[.*] - Version and Configuration Management org.eclipse.webdav[.*] - WebDAV support For example, org.eclipse.jdt.internal.core.compiler - Correct usage org.eclipse.jdt.core.internal.compiler - Incorrect internal should immediately follow subproject name org.eclipse.core.internal.resources - Correct usage org.eclipse.internal.core.resources - Incorrect internal should never immediately follow org.eclipse org.eclipse.core.resources.internal - Incorrect internal should immediately follow Eclipse Platform 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, org.eclipse.core.tests.resources would contain automated tests for API in org.eclipse.core.resources Interactive tests (ones requiring a hands-on tester) should be flagged with interactive as the last package name segment; so, for example, org.eclipse.core.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, org.eclipse.swt.examples would contain examples for how to use the SWT API Additional rules • Package names should contain only lowercase ASCII alphanumerics, and avoid underscore _ or dollar sign $ characters Classes and Interfaces Sun's naming guidelines states 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) Examples: • • class Raster; class ImageSprite; Interface names should be capitalized like class names 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 Additional rules: The names of exception classes (subclasses of Exception) should follow the common practice of ending in "Exception" Methods Sun's naming guidelines states Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized Examples: • • • run(); runFast(); getBackground(); Additional rules: The named of methods should follow common practice for naming getters (getX()), setters (setX()), and predicates (isX(), hasX()) Variables Sun's naming guidelines states 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 _ or dollar sign $ characters, even though both are allowed 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 i, j, k, m, and n for integers; c, d, and e for characters Examples: • • • int i; char c; float myWidth; Constants Sun's naming guidelines states The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_") Examples: • • • static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1; Plug-ins and Extension Points All plug-ins (and plug-in fragments), including the ones that are part of the Eclipse Platform, like the Resources and Workbench plug-ins, must have unique identifiers following the same style of naming convention as Java packages For example, the workbench plug-in is named org.eclipse.ui The names of a plug-in and the names of the Java packages declared within the code library of that plug-in commonly align For example, the org.eclipse.ui plug-in declares much of its code in packages named org.eclipse.ui.* While alignment is the recommended practice, it is not an absolute requirement For instance, the org.eclipse.ui plug-in also declares code in packages named org.eclipse.jface.* The org.eclipse.ant.core plug-in declares code in packages named org.eclipse.ant.core and org.apache.tools.ant.* The plug-in namespace is managed hierarchically; not create plug-in without prior approval from the owner of the enclosing namespace Extension points that expect multiple extensions should have plural names For example, "builders" rather than "builder" System Files and Settings By convention, files or folders that start with a period ('.') are considered "system files" and should not be edited by users or, directly, by other components that not "own" them Of special note is the ".settings" folder in a workspace project This folder holds various forms of preference or metadata specific to that workspace project Files in this directory not have to start with a period (they are assumed "system files" as they are in a "system folder") but they must follow the same naming conventions outlined elsewhere in this guide That is, they must identify themselves with their Eclipse Project's namespace (e.g org.eclipse.jdt, org.eclipse.jst, etc) and they should be as specific as possible to denote the package they come from, or the function they are serving For example, org.eclipse.jdt.core.prefs org.eclipse.jst.common.project.facet.core.prefs org.eclipse.wst.common.project.facet.core.xml Two obvious exceptions to this convention are the classpath and project files, but that's just because they were the first, before the large community of Eclipse was grasped Following these namespace guidelines will help avoid conflicts where two plugins or projects could accidently pick the same name for a metadata file Eclipse User Interface Guidelines (Version 2.1 - 3.x Working Draft) Nick Edgar, Kevin Haaland, Jin Li and Kimberley Peter Last Updated: February 2004 Note: Please use the discussion page to add comments instead of embedding them in this document Note: We have created a section for hosting the drafts of ongoing Eclipse v3.x UI guidelines (Best Practices) updates Go to Eclipse UI Best Practices v3.x updates (Last updated in June, 2006) Notice Your feedback can influence the ideas and guidelines described here If you have suggestions, please provide us with your feedback on the UI mailing list or on the discussion page Introduction In this document the Eclipse user interface guidelines are defined Eclipse is a universal tool platform - an open, extensible IDE for anything, but nothing in particular The real value comes from tool plug-ins that "teach" Eclipse how to work with things - Java™ files, Web content, graphics, video - almost anything you can imagine Eclipse allows you to independently develop tools that integrate with other people's tools so seamlessly, you won't know where one tool ends and another starts The very notion of a tool, as we know it, disappears completely The platform is very flexible and extensible, but this flexibility has a serious drawback In particular, there is no way within the program to ensure user interface consistency between the registered components within the platform This document attempts to reconcile this problem, by defining standard user interface guidelines for the creation of new components If these guidelines are adopted within your own tools, it will lead to greater consistency with the platform and other tools, and an easier learning curve for your customers These guidelines are intended for use by designers and implementors of an Eclipse user interface extension The Workbench To start out, let's take a look at the Eclipse workbench user interface, and the various components within it The workbench is a collection of windows Each window contains a menu bar, a toolbar, a shortcut bar and one or more perspectives A perspective is a visual container for a set of views and content editors The views exist wholly within the perspective and are not shared, but any opened content editors are shared across perspectives If two or more perspectives have the same view opened, they share the same instance of the view although its layout may differ in the perspectives For perspectives in different Workbench windows, neither editors nor views are shared A perspective is like a page within a book It exists within a window along with any number of other perspectives and, like a page within a book, only one perspective is visible at any time The Workbench's main menu bar usually contains the File, Edit, Navigate, Project, Window, Help top-level menus Other top-level menus that are in between the Edit and Project menu are typically context specific, based on the current active perspective, front most editor (whether active or not), and active view In the File menu you will find a New submenu, which contains menu items for Project, Folder, and File creation The File menu also contains menu items for Import and Export, which are used to import files into the Workbench, and export them out again In the Edit menu, you will find familiar commands like Cut, Copy, Paste, and Delete These commands are known as global commands, and target the active part In other words, if the Delete command is invoked with the Navigator active, the actual implementation is performed by the Navigator In the Project menu, you will find project related commands such as Open project, Close project and Rebuild project are available In the Run menu, you will find commands related to running and debugging application code, and launching external tools such Ant scripts In the Window menu, you will find the Open Perspective submenu to open different perspectives to suit to needs of your development tasks You will find perspective layout management menu items You will also find the Show View submenu to add views to the current Workbench window In addition, you will find the Preferences menu item, which is used to modify the functional preferences of the Workbench As a plug-in developer, you can contribute new views, editors, wizards, menu, and tool items to the platform These contributions are defined using XML, and once registered, integrate seamlessly with the components which already exist in the platform Projects, Folders and Files Eclipse can be used to create many different kinds of content - Java files, Web content, graphics, video - almost anything you can imagine These objects are stored as regular files within the Eclipse workspace The workspace consists of one or more top level projects Each project contains a collection of folders and files These objects are known as resources Getting Started For most developers, an introduction to the platform can be overwhelming, and you may ask "where I get started?" Here are a few basic guidelines which will help you This document is intended for UI designers and developers With this audience in mind, we can talk about the two main layers of any application: the model layer and the user interface layer In the model layer of Eclipse, known as the Workspace, is a collection of resources (projects, folders and files) The user interface, or the Workbench, defines the presentation for those resources As a UI developer, you will also have a model and a presentation If we assume that your goal is to make the model visible, through some presentation, most developers will start out by adding a new view or editor to the workbench In Eclipse, an editor is used to contain the primary content, such as a document or data object, which users interact with In every case, this content is the primary focus of attention and a reflection of the primary task To illustrate this concept, let's look at some common examples To Java programming, the primary task is to create, edit, and debug Java code The primary focus is the Java code, so an editor is used to interact with that code The navigator, outline, and properties view exist to support the primary task, but rarely hold your attention for an extended period of time while you are writing Java code To read email, the primary task is to create, send, read, and reply to email The primary focus is a particular email message, so an editor is used to view or reply to an email message A view may be used to select an email message to read, and open an editor To communicate using instant messaging, the primary task is the conversation The primary focus is a particular conversation, so an editor is used to carry on that conversation A view may be used to list people with whom you can initiate a conversation To browse the Web, the primary task is reading The primary focus is a particular Web page, so an editor is used to browse the Web page In each case, the primary task determines the primary focus of attention As the primary focus of attention, it deserves a primary position in the UI (as an editor), and can contribute commands to the workbench's main menu bar and toolbar A view may be used to save your favorite links, and reopen them At any time, you may decide to edit the page you are looking at This causes a new editor to open Views are used to support the primary task You use them to navigate a hierarchy of information, open an editor, or view properties for the active part Each view may have its own local toolbar and local menu bar Once you have added a view or editor, an interesting question arises Where did this model come from? In Eclipse, most data is created using a creation wizard You may want to add a creation wizard too And once an object exists, you may need a way to edit the properties for that object using a properties page, or the properties dialog All of these ideas will be discussed, in detail, in the following sections General UI Guidelines ... named of methods should follow common practice for naming getters (getX()), setters (setX()), and predicates (isX(), hasX()) Variables Sun''s naming guidelines states Except for variables, all... (they are assumed "system files" as they are in a "system folder") but they must follow the same naming conventions outlined elsewhere in this guide That is, they must identify themselves with their... (subclasses of Exception) should follow the common practice of ending in "Exception" Methods Sun''s naming guidelines states Methods should be verbs, in mixed case with the first letter lowercase,