1. Coding
Conventions
Overview of coding conventions.
By THITIPONG JAMPAJEEN

2. What are Coding conventions?
Coding conventions are a set of guidelines for a specific programming
language or recommend programming style.
These conventions usually cover file organization, indentation, comments,
declarations, statements, white space, naming conventions, programming
practices, programming principles,programming rules of thumb,
architectural best practices, etc.

3. What are Coding conventions?
Code conventions are important to programmers for a number of
reasons:
● 40%-80% of the lifetime cost of a piece of software goes to maintenance.
● Hardly any software is maintained for its whole life by the original author.
● Code conventions improve the readability of the software, allowing
engineers to understand new code more quickly and thoroughly.
● If you ship your source code as a product, you need to make sure it is as
well packaged and clean as any other product you create

4. What are Coding conventions?
Software Engineering
Software engineering is the process by which the project is specified and
designed . It is absolutely fundamental to the success of projects ,
particularly if they are large projects . The software engineering process is
what runs the coding process to successful completion . Good software
engineering can make the difference between a successful project - both in
financial and engineering terms - and a project that is , at worst , dead on
delivery . Good software engineering will minimise downstream costs and
maximise the marketing success of the project .

5. What are Coding conventions?
Quality
Software peer review frequently involves reading source code. This type of
peer review is primarily a defect detection activity. By definition, only the
original author of a piece of code has read the source file before the code is
submitted for review. Code that is written using consistent guidelines is
easier for other reviewers to understand and assimilate, improving the
efficacy of the defect detection process.
Even for the original author, consistently coded software eases maintainability.
There is no guarantee that an individual will remember the precise rationale
for why a particular piece of code was written in a certain way long after the
code was originally written. Coding conventions can help. Consistent use of
whitespace improves readability and reduces the time it takes to understand

6. Common Conventions
Programming principles & rules of thumb
● Code smell
Duplicated code: identical or very similar code exists in more than one
location.
Long method: a method, function, or procedure that has grown too large.
Large class: a class that has grown too large. See God object.
Too many parameters: a long list of parameters in a procedure or
function make readability and code quality worse.

7. Common Conventions
Programming principles & rules of thumb (Cont.)
● Code smell
Feature envy: a class that uses methods of another class excessively.
Inappropriate intimacy: a class that has dependencies on
implementation details of another class.
Lazy class / Freeloader: a class that does too little.

8. Common Conventions
Programming principles & rules of thumb (Cont.)
● Code smell
Contrived complexity: forced usage of overly complicated design
patterns where simpler design would suffice.
Excessively long identifiers: in particular, the use of naming conventions
to provide disambiguation that should be implicit in the software
architecture.
Excessively short identifiers: the name of a variable should reflect its
function unless the function is obvious.

9. Common Conventions
Programming principles & rules of thumb (Cont.)
● Code smell
Excessive use of literals: these should be coded as named constants, to
improve readability and to avoid programming errors. Additionally, literals
can and should be externalized into resource files/scripts where possible,
to facilitate localization of software if it is intended to be deployed in
different regions.
Complex conditionals: branches that check lots of unrelated conditions
and edge cases that don't seem to capture the meaning of a block of code.

10. Common Conventions
Programming principles & rules of thumb (Cont.)
● Rule of three is a code refactoring rule of thumb to decide when a
replicated piece of code should be replaced by a new procedure. It states
that the code can be copied once, but that when the same code is used
three times, it should be extracted into a new procedure.

11. Common Conventions
Naming Conventions

12. Common Conventions
Comment conventions

13. Common Conventions
Indent style conventions

14. Best practice / examples?

15. Apache Cloudstack
Java Coding Conventions
These are mostly taken from the Java Programming Style Guidelines with
modifications to reflect current style in Cloudstack. That document is itself
derived from Sun’s original Java Code Conventions document.

16. Apache Cloudstack
Naming Conventions
● Names representing types must be nouns and written in mixed case
starting with upper case, e.g., StoragePool.
● Variable names must be in mixed case starting with lower case, e.g.,
virtualRouter.
● Names representing constants (final variables) must be all uppercase
using underscore to separate words: e.g. MAX_TEMPLATE_SIZE_MB
● Names representing methods must be verbs and written in mixed case
starting with lower case: e.g. copyTemplateToZone.
● Abbreviations and acronyms should not be uppercase when used as
name: e.g. startElbVm

17. Apache Cloudstack
Naming Conventions (Cont.)
● 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.
● Static variables are prefixed with s_: e.g. s_logger
● The is prefix should be used for boolean variables and methods: e.g.
isFinished.
● Exception classes should be suffixed with Exception.
● Default interface implementations can be prefixed by Default or if intended
to be subclassed, suffixed by Base: e.g.:

18. Apache Cloudstack
Files, Layout and Whitespace
● File content must be kept within 120 columns.
● Continuation of lines should be obvious:
totalSum = a + b + c +
d + e;
● Must indent with spaces, not tabs. Indentation = 4 spaces in place of a tab.
● Line endings must be LR (Unix/Linux/Mac format)
● White Space Rules
o Operators should be surrounded by a space character.
o Java reserved words should be surrounded by a white space.
o Commas should be followed by a white space.

19. Apache Cloudstack
Files, Layout and Whitespace (Cont.)
● Block layout should be similar to the example here. Class, interface, and
method blocks should also use this layout:
while (!done) {
doSomething();
done = moreToDo();
}
● If-else clauses, try-catch must use the following layout:
if (condition) {
statements;
} else {
statements;
}

20. Apache Cloudstack
Statements
● Imported classes should always be listed explicitly. No wildcards. The list
of imports should be kept minimal and organized using your IDE
● Class and Interface declarations should be organized in the following
manner:
o Class/Interface documentation.
o class or interface statement.
o Class (static) variables in the order public, protected, package (no
access modifier), private.
o Instance variables in the order public, protected, package (no access
modifier), private.
o Constructors.

21. Apache Cloudstack
Statements (Cont.)
● Type conversions must always be done explicitly. Never rely on implicit
type conversion.
● Variables should be initialized where they are declared and they should be
declared in the smallest scope possible
● Class variables should never be declared public
● Loop variables should be initialized immediately before the loop.
● The conditional should be put on a separate line. This improves
debuggability when there is a failure.
● The use of magic numbers in the code should be avoided. Numbers other
than 0 and 1can be considered declared as named constants instead.

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

23. Apache Cloudstack
Naming Conventions for Design Patterns
● If an interface has only a single implementation, the implementing class
has a suffix Impl
● 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.
● 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 withTO:
e.g., LoadBalancerTO.
● A utility class that encapsulates common utilities (e.g., conversion between
ip address formats) is suffixed with Utils: e.g., NetUtils. These classes
do not hold state. Generally all methods are static.

24. References.
Additional References:
● Java Programming Style Guidelines
● Java Code Conventions
● http://www.mongodb.org/about/contributors/kernel-code-style/
● https://code.google.com/p/google-styleguide/
● http://cloudstack.apache.org/develop/coding-conventions.html
● http://en.wikipedia.org/wiki/Code_refactoring
● http://en.wikipedia.org/wiki/Code_smell
● http://en.wikipedia.org/wiki/God_object