Context Navigation

Coding Standards and Conventions

Coding Standards and Conventions

These standards have been approved by the ArchStudio Community Consensus Process. Any changes must be proposed on the archstudio-dev mailing list.

The establishment of a uniform set of coding standards and conventions makes code throughout the project have a consistent look-and-feel. They can lower the barrier to entry for new developers, because they remove any doubt as to what the code should look like. Good standards can also help to avoid certain common coding errors that are endemic to particular programming languages.

ArchStudio is coded primarily in the Java programming language.

For the Java portions of the code, ArchStudio code should follow the Sun Microsystems Code Conventions for the Java Programming Language. ArchStudio is also an Eclipse application. The Eclipse project uses these same coding conventions as a basis for their own development, as specified here.

Configuration files and templates for Eclipse are available. See the Configuring Eclipse section, below.

Approved Exceptions

Exceptions or refinements to the above coding conventions approved by the ArchStudio community are as follows:

Line Length Relaxation: The Sun coding conventions suggest a line-length maximum of 80 characters for ordinary, non-example code. These lengths are easy to exceed given Java's relative verbosity and long identifiers, especially when using generics. Thus, a maximum line length of 160 characters for ordinary, non-example code is suggested.

Tabs for Indentation, Spaces for Alignment: The Sun coding conventions specify four spaces as the unit of indentation, and tab stops at 8 spaces. The use of tabs for indentation (of, presumably, two levels per tab) is unspecified. Instead, this proposal aims to regularize the use of tabs and spaces as follows. First, the unit of indentation is changed from four spaces to one tab. All indentation is to be done with tabs, indentation with spaces is not permitted. Once indendation is performed, spaces are used to align elements within a line if necessary, and tabs after the initial indentation are not permitted. The primary advantage of this approach is that users can set their tab length to whatever their preference is (2 spaces, 4 spaces, 8 spaces) without encountering mis-aligned code.

else, catch, and finally statements on their own lines: The sun coding standard indicates that else clauses and catch clauses be on the same line as their closing brace. This proposal is to put them on their own lines.

Before:

   if (condition) {
       //Do something
   } else {
       //Do something else
   }

   try {
       //Try something
   } catch (Exception e) {
       //Try something else
   }

After:

   if (condition) {
       //Do something
   }
   else {
       //Do something else
   }

   try {
       //Try something
   }
   catch (Exception e) {
       //Try something else
   }

Use of final keyword: The Sun coding standard says little about the use of the final keyword, which prevents a variable from being modified after its value is set the first time, usually in the constructor of a class. This proposal is to use the final keyword whereever appropriate for member variables in a class. However, public final should not be used in place of a selector (e.g., getVariable()) method.

Rejected Exceptions

Exceptions or refinements to the above coding conventions rejected by the ArchStudio community are as follows:

Elimination of spaces between keywords, braces, and parentheses: The Sun coding standard specifies a space between keywords and the open parenthesis, before open braces, and after closing braces. This proposal is to eliminate those spaces.

Before:

   do {
      //code
   } while (condition);

   if (condition) {
      //code
   }

After:

   do{
      //code
   }while(condition);

   if(condition){
      //code
   }

Proposed Exceptions

Exceptions or refinements to the above coding conventions proposed by the ArchStudio community are as follows, but not yet approved or rejected. Discussions will be held in accordance with the community consensus standard:

None right now.

General Coding Guidelines

Practice extreme-programming-like refactoring. If you're doing copy-and-paste coding, refactor.
Try to be consistent with what's already in the codebase. If you have something slightly different, refactor the existing stuff.

Eclipse Plug-ins

Plug-in ID
- Use a fully qualified Plug-in ID of the form edu.uci.isr.projectX.pluginY, not projectX
- All ISR-developed plugins must be under edu.uci.isr.*
- Do not use a dash ( '-' ) in your ID, use an underscore instead ( '_' )
Plug-in Name
- The plug-in project name (not it's project description, necessarily) should be the same as the Plug-in's ID
Repository Location
- The Plug-in ID should dictate the repository location. The ID edu.uci.isr.projectX.* should be located in the repository at projectX/trunk/edu.uci.isr.projectX.*. This makes it easier to automatically check out and build plugins based on their ID's.
Plug-in Provider: Institute for Software Research, UC Irvine
- TODO: Is this still valid?
Plug-in Version: Use a version number of the form #.#.#.qualifier (actually use the term "qualifier" - the build process will automatically replace the word "qualifier" with an appropriate number
Source folder: should be src
Output folder: should be bin

svn:ignore for projects should include

bin
build.xml
temp.folder
javaCompiler...args
.settings

Source Organization

Packages we develop go under edu.uci.isr.*.
Packages other people develop should be under their own package names or, preferably, in their own plugin.
Resources applicable to one package generally should be in a res directory in that package.
- For generically applicable resources that are ArchStudio-specific, use edu.uci.isr.archstudio4.res.

Licensing Guidelines

Always, always, always add the license terms for any code you import from outside to the license file(s).
BSD License: Preferred. Import as src or jar, modify as you like.
Apache License: Preferred. Import as src or jar, modify as you like.
CPL (Eclipse) License: Acceptable. Import as src or jar, modify but know that modifications of that stuff may have to also be redistributed under CPL.
LGPL License: Acceptable but avoid if alternatives are available. Import as jar only, not src. If you modify, redistribute source as a separate project.
GPL License: Not acceptable. Do not use.
Other Weird License: Post to archstudio-dev@… list.

Icons / Images / Fonts

When in doubt, follow the branding guidelines.
DO NOT STEAL ICONS FROM GOOGLE IMAGES. Draw your own, reuse an Eclipse one, or get one under license.
Reuse Eclipse icons (presumbably distributed under CPL) where possible for functional elements.
Within reason, follow these guide lines for eclipse icons.
Icons should be 16x16 or 32x32 as appropriate. PNG and GIF are preferred. Make icons transparent where possible.
There is already a large set of consistently-designed and useful icons in edu.uci.isr.archstudio4.res that conform to ArchStudio iconography (e.g., components are double-outlined and in Archipelago Blue, connectors are single-outlined and in Archipelago Buff).
The ArchStudio 4 Logo is very similar to the ArchStudio 3 logo (gradient background in ArchStudio blue, white sans-serif text, etc.) with a few minor differences:
- The font for "ArchStudio 4" is Humanst521 Cn BT
- The subtitle font is Zurich Cn BT.
  - These fonts are both close in feel to Frutiger (the old ArchStudio and current ISR font) but are more compact and modern-looking.

Cross-Cutting Stuff

Generally useful utility methods go in edu.uci.isr.*utils plugins located in http://tps.ics.uci.edu/svn/projects/utils/trunk/
- These are generally separated by underlying library so that applications using the utilities do not have surprise dependencies on libraries because of the utility methods.
Generically useful classes and methods that are ArchStudio-specific go in edu.uci.isr.archstudio4.util

Configuring Eclipse

A number of configuration files and templates are available to help maintain these coding standards. These files are available in the main ArchStudio plugin.

Download in other formats:

Plain Text