Hi,
This is the guideline we used in WSO2, shall we have a look and see whether
we can use the same. Please share your thoughts. After we finalised will
put this into wiki and make it as common guide line.
Comments
-
Doc comments
-
All classes and all methods/functions MUST have doc comments
-
Explain each parameter, return type and assumptions made
-
Line comments
-
In case you have complex logic, explain any genius logic, rationale for
doing something
Logging
-
Log then and there
-
With ample local information and context
-
Remember logs are for users. Make them meaningful, readable and also
make sure you spell check (ispell)
-
Use correct log level, e.g do not log errors as warnings or vice versa
-
Remember to log the error before throwing an exception
Logic
-
Make your genius code readable
-
Use meaningful variable names. Remember, compilers can handle long
variable names
------------------------------
-
Variables declared in locality, as an when required
-
The underscore character should be used only when declaring constants,
and should not be used anywhere else in Java code
-
Make sure the function/method names are self descriptive
-
One should be able explain a function/method using a single sentence
without conjunctions (that is no and/or in description)
-
Have proper separation of concerns
-
Check if you do multiple things in a function
-
Too many parameters are smelly, indicates that something is wrong
-
Use variables to capture status and return at the end whenever possible
-
Avoid status returning from multiple places, that makes code less
readable
-
Be consistent in managing state e.g. Initialize to FALSE and set to TRUE
everywhere else
-
Where does that if block end, or what block did you end right now? Have
a comment at end of a block at }
-
Use if statements rationally, ensure the behavior is homogeneous
-
In case of returning a collection, must return an empty collection and
not null (or NULL)
-
Do not use interfaces to declare constants. Use a final class with
public static final attributes and a private constructor.
-
Always use braces to surround code blocks ({}) even if it is a single
line.
-
Break code into multiple lines if it exceeds 100 columns
-
Align method parameters, exception etc. in order to improve readability.
Use the settings in your IDE to do this.
-
Be sure to define, who should catch an exception when throwing one
-
Be sure to catch those exceptions that you can handle
-
Do not use string literals in the code, instead declare constants and
use them, constant names should be self descriptive
-
Use constants already defined whenever possible, check to see if someone
already declared one, specially in base libs, like Axis2
Java Specific
-
Coding conventions -
http://www.oracle.com/technetwork/java/codeconv-138413.html
-
Only exception is line length, we use 100
-
Run FindBugs on your code - http://findbugs.sourceforge.net/
-
Use CONSTANT_VALUE.equals(variable_name) to avoid null pointer exceptions
IMPORTANT
You should run FindBugs on your new code or modified code, and commit only
after fixing any bugs reported by FindBugs. It is recommended to use the
IntellijIDEA (FindBugs-IDEA) or Eclipse FindBugs plugin to do this.
--
Lakmal Warusawithana
Vice President, Apache Stratos
Director - Cloud Architecture; WSO2 Inc.
Mobile : +94714289692
Blog : http://lakmalsview.blogspot.com/
