From Aptana Development

Code Submission Checklist

• License header at top of file
• Code passes all Checkstyle checks
• Code passes all PMD tests
• Code is formatted according to Aptana conventions
• Strings are externalized
• Code is spell-checked
• Code has class/method and field-level Java Docs for public and protected members
• There is at least one unit test for the checked-in code, preferably that does not need to run as a plugin.. Comments should be _relevant_

Basic Coding Guidelines

• Interfaces begin with 'I'
• There are no empty try/catch blocks
• Abstract classes and interfaces should not be in the same package as implementing classes
• Don't call abstract methods in constructors (See here for an explanation: http://www.artima.com/forums/flat.jsp?forum=226&thread=113723)
• Above all, the code should elegant. It should be well-spaced and easy to follow.
• Many of these rules are encapsulated by the Checkstyle and PMD tests
• Private variables may begin with an underscore, but we specifically do not follow the Eclipse 'f' prefix convention. You should be consistent within your class.

For those contributing to the Aptana source code base, we follow a few conventions.

License

Please ensure that the following header is at the top of each source file, or at least an equivalent header. We must have code which is EPL-compatible for the EPL plugins, and GPL compatable for all other plugins:

Dual

/**
* This file Copyright (c) 2005-2007 Aptana, Inc. This program is
* dual-licensed under both the Aptana Public License and the GNU General
* Public license. You may elect to use one or the other of these licenses.
* 
* This program is distributed in the hope that it will be useful, but
* AS-IS and WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, TITLE, or
* NONINFRINGEMENT. Redistribution, except as permitted by whichever of
* the GPL or APL you select, is prohibited.
*
* 1. For the GPL license (GPL), you can redistribute and/or modify this
* program under the terms of the GNU General Public License,
* Version 3, as published by the Free Software Foundation.  You should
* have received a copy of the GNU General Public License, Version 3 along
* with this program; if not, write to the Free Software Foundation, Inc., 51
* Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
* 
* Aptana provides a special exception to allow redistribution of this file
* with certain Eclipse Public Licensed code and certain additional terms
* pursuant to Section 7 of the GPL. You may view the exception and these
* terms on the web at http://www.aptana.com/legal/gpl/.
* 
* 2. For the Aptana Public License (APL), this program and the
* accompanying materials are made available under the terms of the APL
* v1.0 which accompanies this distribution, and is available at
* http://www.aptana.com/legal/apl/.
* 
* You may view the GPL, Aptana's exception and additional terms, and the
* APL in the file titled license.html at the root of the corresponding
* plugin containing this source file.
* 
* Any modifications to this file must keep this entire header intact.
*/

EPL

/**
 * Copyright (c) 2005-2007 Aptana, Inc.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html. If redistributing this code,
 * this entire header must remain intact.
 */

Checkstyle

We use checkstyle to make sure that we keep our code relatively free of possible bugs. It's automatically referenced as part of each project as a "remove configuration" so just download the latest version of the checkstyle plugin:

1. Within Eclipse go to Help->Software Updates->Find and Install
2. Choose Search for new features to install and press Next
3. Create a New Remote Site...
4. Input a name to your liking (for instance Checkstyle Plug-in) and input the following URL: http://eclipse-cs.sourceforge.net/update
5. Click your way through the following pages to install the plug-in.

For those interested, our checkstyle file is located at: http://www.aptana.com/development/aptana_checkstyle.xml

PMD

We use PMD for the items checkstyle doesn't catch.

1. Within Eclipse go to Help->Software Updates->Find and Install
2. Choose Search for new features to install and press Next
3. Create a New Remote Site...
4. Input a name to your liking (for instance PMD Plug-in) and input the following URL: http://pmd.sf.net/eclipse
5. Click your way through the following pages to install the plug-in.

For those interested, our PMD file is located at: http://www.aptana.com/development/aptana_pmd_rules.xml

You will need to download that file, set PMD preferences, clear out the existing rule set, and import the new one from this file. You can then manually run PMD on a file or package from the right-click menu.

Java Formatting

Our Java formatting conventions are relatively easy going, though we do add braces, always.

1. Download the file from http://www.aptana.com/development/aptana_code_standard.xml
2. Within Eclipse go to Window->Preferences->Java->Code Style->Formatter
3. Click on "Import..." and choose the file you just downloaded

Externalized Strings

1. Right-click on a file, choose "Source", "Externalize Strings". Make sure the "Use Eclipse's String Mechanism" is checked. (See how this has been done this elsewhere, with a Messages class and a messages.properties file)
   1. This will require you to change the "Common Prefix". Just replace the '.' with a '_'. i.e. FileExplorerView. becomes FileExplorerView_
   2. You will need to manually rename the keys that are to be externalized from the auto-numbers it creates. Just type something useful, like a pascal-cased shorthand for the original string: "ThisIsAnErrorMessage".
2. Do the externalization per-package, not per-plugin.
3. Important: make sure you add the messages.properties file to the build.properties file. You want to make sure that message.properties file is included in the binary build.
4. Exclude all strings in any unit testing plugins, or any case where it does not make sense to translate that piece of text.
5. Important: Use StringUtils.format() instead of "string " + variable. Again, take a look at how we use this elsewhere. The easiest way to do this is to try and run the externalization wizard. Notice where you have "constructed" strings. Cancel out of the wizard, and then fix them. Then run the wizard again.
6. Make sure you add the messages.properties file to source control
7. Also ensure that you comment all the methods in the messages file to remove any generated warnings

Spell Checking

1. See the instructions here on how to turn on spell checking: http://www.javalobby.org/java/forums/t17453.html
2. Use the dictionary file located here: http://www.aptana.com/development/dictionary.zip

Javadoc Conventions

1. Under Window > Preferences > Java > Compiler > Javadoc, use the following settings

Unit Testing

1. Ensure that the current set of unit tests run before submitting your code, especially if it is a high-risk addition
2. Make sure you've added new unit tests for the new items you've added. If you can't unit test it, write a unit test for something else.