Coding

ConventionsOverview of coding conventions.

By THITIPONG JAMPAJEEN

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.

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

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 .

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

the software.

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.

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.

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.

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.

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.

Common Conventions

Naming Conventions

Common Conventions

Comment conventions

Common Conventions

Indent style conventions

Best practice / examples?

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.

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

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.:

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.

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;

}

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.

o Methods (no specific order).

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.

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

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.

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