We are working together to develop a large code base. We plan that this code base will live for a long time. Software development techniques and group process, including good programming style and other formal communication, are all that is between us and complete chaos.

The structure of code has an enormous impact on readability, maintainability, and efficiency. When you work on the code base, you are not just creating functionality. You are contributing to an API. Make your code as nicely structured, clear, and well documented as you want to see when you deal with code that you didn't write!

People will depend on your code! Even if you move on. Clarity is essential. It's not so hard to write code that works initially. Writing maintainable code is a greater challenge.

To increase each developer's ability to easily read someone else's code -- both as it's being written, and later, when it's being maintained -- it is valuable for all of us to use a common style, and a coherent process. This guide has evolved through years of practice. All involved in the lab and/or in S.IM.PL are expected to either follow these conventions, or work to develop a consensus to amend them.

1. Before you commit code to the repository, find or develop meaningful test cases. Make sure it passes them. Ask others for input on this.
2. When you do commit code, talk to those who depend on it to see if it is working for them. Generally make yourself available, in case you've broken something that they need.
3. Use meaningful names for variables, not short unreadable ones. These are a principal form of documentation for your code. Exception: use of i, j, k for index variables.
4. Write clear Doc comments for all packages, classes, methods, and instance variables. For methods, the Doc comment should explain the purpose of the method, the arguments, and the return value.
5. Inject comments into the midst of your code to explain anything tricky or subtle.
6. Use temporaries, also known as local variables whenever a computed or dereferenced value is used more than once. Primary Benefit: The computations of method calls, and pointer dereferencing have an associated computational overhead. Temporary variables usually go into CPU registers, where they can be accessed extremely rapidly. Side benefit: You get to author a name for the temporary variable, which can help make the function/meaning of it clear to the next programmer.
7. Class names in Java, C#, and similar languages.
   • Capitalized. First letter in upper case, then lower case, until
   • word breaks, which are delimited by upper case.
   Examples: MetaMetadata, HttpServlet
8. Variables in Java, C#, Objective C, and JavaScript.
   • All letters are in lower case, except for
   • word breaks which are delimited by upper case.
   Example: geoCoordinate, semanticsSessionScope
9. Package names in Java, C#, and similar languages.
   • lower case. No word breaks.
   Example: ecologylab.serialization
10. Constants in Java, C#, Objective C, and JavaScript. (static final variables).
    • All letters are UPPER CASE.
    • Word breaks are separated by underscore.
    Example: COLLECTION_SCALAR, REPOSITORY_METADATA_TRANSLATIONS
11. Method names in Java and function names in JavaScript.
    • All letters are in lower case, except for
    • word breaks which are delimited by upper case.
    Example: performAction(), handleIoError(...)
12. Variables in SQL and HTML forms.
    • All letters are lower case.
    • Word breaks are delmited by underscore.
    Example: last_name, name_id.
13. Variables and subvariables in Cookies.
    • All letters are UPPER CASE. (This is an exception, because Microsoft IIS forces them to be named this way, in most cases.)
    • Word breaks are separated by underscore.
    Example: USER, FIRST_NAME
14. HTML.
    • Tags and attributes: All letters are lower case.
    • URL String arguments:
      All letters are in lower case, except for word breaks which are delimited by upper case.
    Example: relId, relType
15. Judiciously use whitespace to enhance the readability of code. This includes horizontal whitespace, such as (tabs to line up columns), and vertical whitespace (such as a blank line between important functional sections). Some specifics:
    • Open and close brace on a line by themselves.
    • Spaces after all reserved words.
    • 1 space after the equals sign; at least 1 before it (lining up the = in assigments is nice), except on rare occassions to get vertical matching with a bunch of other declarations.
    • 1 space before and after arithmetic and logical operators.
    • Space before open paren in expressions (but not in method declarations), and after close paren. But NO SPACE after open paren or before close paren.
    • Line up declarations and assignements with horizontal tab.
    Dont be excessive: having lots of extra, meaningless blank vertical lines just makes it harder to see a block on the display while programming. Likewise, too much horizontal space causes wraps in smaller windows and with maller monitors. Please strive to make it readable by all developers. Example:

     
    public class Foo
    extends Debug
    {
       int			sumOfAngles;
       public static final	RIGHT_ANGLE	= 90;
       public static final	BAD_FILE	= -37;
       public static final	GOOD_FILE	= 0;
       
       public int contributeAngle(int newAngle)
       {
          if (a == b)
          {
    	 int x		= 33;
    	 sumOfAngles   += x + newAngle;
          }
          try
          {
    	 InputStream inStream	= new FileInputStream(inFile);
    	 inStream.open();
          } catch (Exception e)
          {
    	 println("Couldnt open file " + inFile);
    	 return BAD_FILE;
          }
          return GOOD_FILE;
       }
    }
    

    Note, for example: if(a==b) is just plain anti-social.