Project teams work together to develop a code base. It is expected that the code bases will live for a long time. The code base grows extremely large. Software development techniques, such as good programming style, are all that is between us and complete chaos.

When you work on the code base, you are not just creating functionality. You are conributing to the API. Make your code as nicely structured, clear, and well documented as you want to see when you look at functionality that you didn't write!

You may leave the project at some point; your code lives on (sort of like being in two places at once, or being immortal :-). People will still depend on your code! 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. This involves naming conventions and white space. I am making this explicit.

This style guide has evolved through years of use. The specifics are open for discussion, anytime. I expect everyone involved in the lab to either follow these conventions, or work to develop a consensus to amend them.

Although this guide has been developed primarily for Java, the same conventions are applicable for other imperitive languages such as C#, C++ and objective-C.

1. Use meaningful names for variables, not short unreadable ones. You can use i, j, k for index variables, though.
2. HTML and Image filenames.
   1. All letters are in lower case, except for
   2. word breaks which are delimited by upper case.
   3. Suffixes are lowercase.
   Examples: whatIsIt.html, topLogo.gif
3. Variables in SQL and HTML forms.
   1. All letters are lower case.
   2. Word breaks are delmited by underscore. Examples: last_name, name_id.
4. Variables in Java and JavaScript.
   1. All letters are in lower case, except for
   2. word breaks which are delimited by upper case.
   Examples: nameId, printName
5. Variables and subvariables in Cookies.
   1. All letters are UPPER CASE. (This is an exception, because Microsoft IIS forces them to be named this way, in most cases.)
   2. Word breaks are separated by underscore.
   Examples: USER, FIRST_NAME
6. Constants in Java (final variables).
   1. All letters are UPPER CASE.
   2. Word breaks are separated by underscore.
7. Method names in Java and function names in JavaScript.
   1. All letters are in lower case, except for
   2. word breaks which are delimited by upper case.
   Examples: doDispatch(), printValue(...)
8. Class names in Java.
   1. Capitalized. First letter in upper case, then lower case, until
   2. word breaks which are delimited by upper case.
   Examples: HotButton, HttpServlet
9. Package names in Java.
   1. lower case. No word breaks.
   Example: cm.generic
10. Tags and attributes in HTML.
    1. All letters are lower case.
    2. URL String arguments in HTTP/HTML
       1. All letters are in lower case, except for
       2. word breaks which are delimited by upper case.
       Examples: relId, relType
11. Whitespace will be used judiciously 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 smaller 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.
12. Clear JavaDoc comments for all packages, classes, methods, and important instance variables. For methods should explain the purpose of the method, the arguments, and the return value.
13. Comments in the midst of your code, to explain anything tricky or subtle.
14. For Java Developers who use eclipse (why wouldn't you ?), the code formatter is a great utility. Set the code formatter to use the ecologylab recommended settings (available here with anonymous access) by navigating to Window (Eclipse on Mac) > Preferences > Java > Code Style > Formatter and clicking on import. Any Java code can be formatted by using the keyboard shortcut control (command on a Mac) + shift + F.