Scribd
Upload
44 views

Coding Conventions

1. The coding conventions adhere to Oracle Java Coding Conventions where possible. 2. Class and variable names should be descriptive. 3. Use spaces instead of tabs and indent code by 4 spaces. 4. Always use braces for if/else statements and loops to avoid bugs.

Uploaded by

manu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
44 views

Coding Conventions

1. The coding conventions adhere to Oracle Java Coding Conventions where possible. 2. Class and variable names should be descriptive. 3. Use spaces instead of tabs and indent code by 4 spaces. 4. Always use braces for if/else statements and loops to avoid bugs.

Uploaded by

manu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 5

Coding Conventions

The coding conventions should adhere to the Oracle Java Coding Conventions as much as
possible.

File templates
IntelliJ by default will add class level Javadoc that contains the User name, Date, and Time the
file was created. If the class requires Javadoc, remove the User, Date, and Time information.
This information adds no value and is readily available in version control. If the class requires no
Javadoc, remove the entire comment.

Class and Variable Naming


 First and foremost, naming should be descriptive. Don't worry about how long names are;
the IDE can autocomplete nearly anything. Readability and understanding are more
important that typing fewer characters.
 Implementation class names should be descriptive and not simply have "Impl" stuck on
the end of the interface name that they implement. If you have an interface then there
could be multiple implementations of that interface. Naming the implementation
descriptively is clearer than just sticking "Impl" on the end.
 Variables (class variables, local variables, etc) should not use any special notation to
indicate their type or scope, meaning no variable names that start with underscores or
Hungarian notation or anything else. Similarly, interfaces should not start with "I".
 Constants should be static and final and all uppercase with underscores separating the
words.
Example:

// Interface Naming
public interface IUserService {...} // BAD
public interface UserService {...} // GOOD

// Implementation Naming
public class UserServiceImpl implements UserService {...} // BAD
public class HibernateUserService implements UserService {...} // GOOD
public class JdbcUserService implements UserService {...} // GOOD
// Variable Naming
private String _serviceName; // BAD
private String szServiceName; // BAD
private String serviceName; // GOOD

// Constant Naming
public static final int maxTimeoutSeconds = 30; // BAD
public static final int MAX_TIMEOUT_SECONDS = 30; // GOOD

Spaces vs. Tabs


 Use spaces, not tabs, because if you open the file in a plain text editor, tabs will make the
code fall off the right-hand side of the screen.
 4 spaces per tab.

Line Wrapping
 Generally, wrapping lines is discouraged, except for conditional statements. We all have
wide monitors so code rarely runs outside the right edge of the window. However, if you
strongly feel wrapping makes the code easier to understand then you can wrap it.
 When wrapping conditionals, follow Java conventions, which is to break before the
operator so the next line begins with the operator.
Example:
if ((condition1 && condition2)
|| (condition3 && condition4)
|| !(condition5 && condition6)) {
doSomethingAboutIt();
}

Design with Interfaces


Java's interface construct allows you to define an abstract interface without specifying any
implementation. This interface allows you to articulate in a general way what contract obtains
between a concrete implementation class, the methods it exposes for public use, and the users of
that interface. In other words, interfaces allow one to decouple an implementation from its
published contract. The implementation can vary, but the interface does not. So if you program
to, or depend on, interfaces, it is much easier to refactor your code and much easier to unit test it
by using mock implementations of that interface. There is another benefit: an implementation
class can implement more than one formal interface and thus affect some degree of
polymorphism, whereas the same class in Java cannot extend multiple concrete classes.

Field and Method Declaration Order


Same as Java, just explicitly calling it out here. See Java Code Conventions.
For methods, including accessors, follow the same conventions as class and instance variables:
first public, then protected, then package level (no access modifier), and then private.
Example:

// static finals
public static final AAA;
protected static final BBB;
static final CCC;
private static final DDD;

// statics (although, they should probably be final unless you really know what you are doing)
public static EEE;
protected static FFF;
static GGG;
private static HHH;

// fields
public iii;
protected jjj;
kkk;
private lll;

Javadoc
See How to Write Doc Comments for the Javadoc Tool.
 JavaDoc is at the developer’s discretion. It is encouraged when you think it will be
helpful.
 The only requirement would be DRY (don't repeat yourself); if there is any
JavaDoc/comment, it should add information not provided in the member name or
parameters or types or code itself, such as pre-conditions and post-conditions in a
interface, which cannot be coded. Anything that can be somehow coded, should be done
so, such as pre-conditions and post-conditions in a method implementation.

Braces
Always use braces, even for single statement if statements and looping constructs, to avoid
unintentional bug introduction when the body changes.
Braces should never be on a line on their own; they should follow the statement (like Java's
convention).
Example:

// BAD
if (condition)
{
doSomethingAboutIt();
}

// GOOD
if (condition) {
doSomethingAboutIt();
}

Method Variable Declaration and Assignment


 Variables should be declared and assigned once they are needed ("as late as possible"
policy).

Character Encoding
 All our source code and non-property file resources must be UTF-8 encoded.
 Property files must be encoded as ASCII with any non-ASCII characters escaped with
unicode escape sequences "\uxxxx". See Converting Non-Unicode Text or Unicode
Escapes for more information.
 The JDK ships with a native2ascii tool to convert native characters. As of June 29, 2010,
our maven build uses the UTF-8 encoding by default, see Maven character encoding for
more information.

Parenthesis
 Unnecessary parentheses around conditionals are exactly that -- unnecessary.

Syntax

Constants
 upper case snake case (for example: THIS_IS_A_CONSTANT)
Variable names
 lower case snake case (for example: this_is_a_variable)
 use meaningful names
Functions
 lower case snake case
 name starts with a verb (for example: get_function, set_function,
do_function, show_function)
Indent 4 spaces for loops, if...then
Do not duplicate code
Abstract out common functions, etc.
Check for errors and exit with message - should we use error_exit() everywhere?
Use command chaining (&& and ||) only when needed
Use jq for all operations on json.
Create functions for common jq operations.
Create functions for common file manipulation functions.

You might also like