Overview

This document covers coding style common in Cloudstack development. It covers coding in Java, shell script, Python and database naming conventions. It does not always cover coding best practices (although there will be some overlap).

Although the document talks mostly about conventions, certain items are ‘must’ while others are ‘should’ and ‘can’.

In all cases, correctness of the code is paramount, followed by readability, followed by these conventions.

It is also important to not introduce formatting changes in existing code in the attempt to conform to these conventions: this makes it hard to track logic changes vs. formatting changes in the code. If an existing code block is being rewritten extensively then it makes sense to adopt these conventions.

Copyright and License

All source code should bear the ASF license header as detailed here:

http://www.apache.org/legal/src-headers.html#headers

Java Coding Conventions

These are mostly taken from http://geosoft.no/development/javastyle.html with modifications to reflect current style in Cloudstack. That document is itself derived from Sun’s original Java Code Conventions document.

Naming Conventions

1. Names representing types must be nouns and written in mixed case starting with upper case. E.g., StoragePool
2. Variable names must be in mixed case starting with lower case, E.g., virtualRouter
3. Names representing constants (final variables) must be all uppercase using underscore to separate words. E.g., MAX_TEMPLATE_SIZE_MB
4. Names representing methods must be verbs and written in mixed case starting with lower case. E.g., copyTemplateToZone
5. Abbreviations and acronyms should not be uppercase when used as name. E.g., startElbVm
6. Private class variables should have underscore prefix. E.g., _downloadTimer. Exception: Transfer Objects (TOs), Database objects (VOs), Command objects:- private class variables in these classes have no underscores. The exception is justified since these are usually logged and are more readable without underscores.
7. Static variables are prefixed with s_. E.g., s_logger
8. is prefix should be used for boolean variables and methods. E.g., isFinished
9. Exception classes should be suffixed with Exception.
10. Default interface implementations can be prefixed by Default or if intended to be subclassed, suffixed by Base. E.g., DefaultExternalNetworkElement or NetworkElementBase
11. There are various naming conventions used to convey the design patterns common in Cloudstack, listed in the Appendix.

Files, Layout and whitespace

1. File content must be kept within 180 columns

2. Continuation of lines should be obvious:

   totalSum = a + b + c +
       d + e;
   

3. Must indent with space not tabs. Indentation = 4 spaces
4. Line endings should be LR (Mac / Linux format)
5. White space:
   1. - Operators should be surrounded by a space character.
   2. - Java reserved words should be followed by a white space.
   3. - Commas should be followed by a white space.
   4. - Colons should be surrounded by white space.
   5. - Semicolons in for statements should be followed by a space character.

6. Block layout should be as illustrated below . Class, Interface and method blocks should also use this layout.

   while (!done) {
       doSomething();
       done = moreToDo();
   }
   

7. If-else clauses must use the following layout:

   if (condition) {
       statements;
   } else {
       statements;
   }
   

8. The try-catch block follows the if-else example above

Statements

1. Imported classes should always be listed explicitly. No wildcards. The list of imports should be kept minimal and organized using your IDE
2. Class and Interface declarations should be organized in the following manner:
   1. Class/Interface documentation.
   2. class or interface statement.
   3. Class (static) variables in the order public, protected, package (no access modifier), private.
   4. Instance variables in the order public, protected, package (no access modifier), private.
   5. Constructors.
   6. Methods (no specific order).
3. Type conversions must always be done explicitly. Never rely on implicit type conversion.
4. Variables should be initialized where they are declared and they should be declared in the smallest scope possible
5. Class variables should never be declared public
6. Loop variables should be initialized immediately before the loop.
7. The conditional should be put on a separate line. This improves debuggability when there is a failure.
8. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1can be considered declared as named constants instead.

Comments

1. Tricky code should not be commented but rewritten. Code should be self documenting
2. Code that parses special input strings (e.g, comma delimited) should provide examples of valid strings in comments
3. Use // for all non-JavaDoc comments, including multi-line comments
4. Comments should be in English
5. Comments should be indented relative to their position in the code
6. All public classes and public and protected functions within public classes should be documented using the Java documentation (javadoc) conventions

Libraries

1. For string operations, org.apache.commons.lang3.StringUtils must be used. For operations not covered by org.apache.commons.lang3.StringUtils, the facade com.cloud.utils.StringUtils must be used.

Database Conventions

1. All SQL keywords are all-caps
2. Naming:
   1. Table and column names are lower case with underscore separating words
   2. Indices (including UNIQUE) are lower case of the form i_<table name>_<column name>
   3. Foreign key constraints are of the form fk_<table name>_<foreign table name><foreign column_name>
3. All CREATE TABLE’s should have the corresponding DROP TABLE IF EXISTS at the top of the file.
4. Database engine must always be InnoDB. Charset should always be UTf8
5. Primary keys are always bigint unsigned NOT NULL UNIQUE AUTO_INCREMENT
6. Tables intended for operational purposes, usually transient data should be prefixed with op_ (e.g., op_lock)
7. Columns should always be commented unless obvious
8. Examine each column to choose your indexes. More indexes can mean more tablespace usage (but this is usually trivial) but better performance. More indexes also increase the possibility of deadlocks.

Shell Script

The current state of shell scripts inside Cloudstack is fairly inconsistent. Will update later

Python

1. All Python code must be PEP-8 compliant
   1. All existing code fails this test.
2. TODO

IDE settings file

Eclipse

• The eclipse settings file is checked-in in git with the code. You can find it at tools/eclipse/eclipse.epf
• The formatter xml exported from the above epf is ApacheCloudStack.xml
• It is available in git repo @ https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=blob_plain;f=tools/eclipse/ApacheCloudStack.xml;hb=HEAD

Intellij Idea

• A WIP settings jar for java and xml files intellij-idea-settings.jar
• Use the Eclipse Code Formatter plugin and the setting from the above eclipse xml file ApacheCloudStack.xml

Appendix

Naming Conventions for Design patterns used in Cloudstack Java code

1. If an interface has only a single implementation, the implementing class has a suffix Impl
2. A class that maps to a database table is known as a Value Object and is suffixed with VO. E.g., NetworkVO. This actually maps to the EJB DTO pattern rather than the EJB VO pattern
3. A class that transfers data from one tier to another (e.g., from the business logic tier to the resource layer) is a Transfer Object and is suffixed with TO. E.g., LoadBalancerTO.
4. A utility class that encapsulates common utilities (e.g., conversion between ip address formats) is suffixed with Utils. Eg., NetUtils. These classes do not hold state. Generally all methods are static.
5. Services offered by the business tier to the API tier are declared as interfaces and are suffixed by Service. E.g., LoadBalancerService
6. Singleton classes that implement lifecycle functions are called Managers. E.g., AgentManager
7. Data Access Objects (DAOs) implement the J2EE DAO pattern. They are generally declared as interfaces suffixed with DAO and then implemented as classes with the DaoImpl suffix. E.g., AccountDao _and AccountDaoImpl_
8. The Cloudstack API layer implements the Command pattern. All API commands are suffixed with Cmd. E.g., DeployVmCmd.
9. The internal API layer between the business tier and the resource layer also uses the Command pattern. These classes are suffixed with Command. Responses to these commands are suffixed with Answer. E.g. ModifyStoragePoolCommand and ModifyStoragePoolAnswer.
10. Resources are managers that respond to the internal API commands. E.g. XenServer56Resource

References

[1] Java Programming Style Guidelines http://geosoft.no/development/javastyle.html

[2] Java Code Conventions http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Attachments