=== WHAT ===Coding convention (quy ước viết mã) : set of conventions (recommendations) for naming, formatting, and documentation requirements.
Coding standard of XYZ (chuẩn viết mã của XYZ) : set of standards (rules) of XYZ for naming, formatting, and documentation requirements.
Coding style (phong cách viết mã): the way somebody writes code and layouts. To get more effective and productive when programming, we should have common coding style and good practices; therefore we should follow practical coding conventions or coding standards.
=== WHY ===The first and most important reason is
Readablity (and
reusability, of course) : easier for developers to read and understand each other's code . As a result:
+ Quicker adapt to source code of new project, regardless of debugging/
testing/coding
+ Quicker transfer knowledge across projects, very useful for newcomers
And also the conventions can
reduce name confliction, make
better proliferation (e.g.
pointTotal, totalPoints),
emphasize relationship among related items (e.g.
Customer { customerName, customerAddress, ... } ) , and
compensate for language's weaknesses .
=== WHEN ===+ Multiple developers are working on a project.
+ Your program is so large that you can't hold the whole thing in your brain at once and must think about it in pieces.
+ The program will be long-lived enough that you might put it aside for a few weeks or months before working on it again.
+ Plan to turn a program over to another programmer for modifications and maintenance (which is nearly always).
+ Your programs are reviewed by other programmers in your organization.
=== HOW ===Here are some
recommended coding conventions for
Java, yet it can be applied for other popular programming languages (PHP, ActionScript, Ruby, ...) , with a slight modification.
+
File name: should be
alphanumeric (to be exact: [A-Za-z][A-Za-z0-9] ) and
underscore ( _ ) , hyphen ( - ) , dot ( . ) only . Fortunately the Java compiler requires ".java" as an extension , and it will produce ".class" byte code file, so we can prevent some sudden inspiration with file names :D .
+
File organization: In a file, we should use blank lines to separate sections, make it clean and clear. Usually 1 or 2 blank lines is sufficient, depends on how "big" that section is. In some extreme case we can use 3 blank lines to separate. Note that in modern languages such as Java we can alway separate a big program into at least several classes (and corresponding files) , so a file with more than 2000 lines is cumbersome and should be divided (to conquer) !
+
File sections: should be the following order: header comments, package declaration, import declaration, main class/interface, internal classes (if exists). Example:
/*
* @(#)MyClass.java 1.54, 2008 Jan 01
*
* Copyleft 2008 Mediocre-Ninja. Use is subject to license terms.
*/
package org.opensource;
import java.io.Serializable;
/**
* This is the dummy class for demonstration.
*
* @author Mediocre-Ninja
* @author unascribed
* @since 2008 Jan
*/
public class MyClass {
//...
}
class MyInternalClass {
//...
}
+
Class (or interface) declaration: should be the following order
- Class or interface statement
- Class or interface implementation comment, if necessary
- Class (static) fields: public, protected, private
- Instance fields: public, protected, private
- Constructors.
- Method: grouped by functionality rather than by scope
+
Indentation, line length and breaks: as following
- A tab width is considered "indentation unit", but
replace the tab character by 2-4 spaces. [
CONTROVERSIAL] The concrete number of spaces depends on the project. Usually 4 spaces for Java/JavaScript, 3 spaces for ActionScript/MXML/XML, 2 spaces for Python/Ruby/Perl/C...
- Try to avoid lines longer than 80 characters, since they’re not handled well by many terminals and tools.
- Principles when breaking lines: break AFTER A COMMA, break BEFORE AN OPERATOR, align the broken line as the same indentation (if it leads to confusing code then use 1 more "indentation unit", i.e. total 2 "units")
- Example:
longNameResult = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6;
var = someMethod1(longExpressionHere,
someMethod2(longExpressionAgain,
longExpressionYetAnother));
if ( (condition1 && condition2) || (condition3 && condition4)
|| !(condition5 && condition6) ) {
doSomethingAboutIt();
}
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
//...
}
alphaResult = (aLongBooleanExpressionForTernaryOne)
? betaValueHere
: gammaExpressionHere;
+
Comments: in Java can be classified as 2 kinds: Documentation (javadoc) comments, and implementation comments (both block comment (C-style) and line comment (C++ style) ).
- trailing comments should be seperate (i.e. at least 1 space) from the semi-colon or left-most character
- non-trailing comments should be preceded by a blank line
- summary points should be in uppercase. Example: // TO DO: , // FIX ME:
+
Naming convention:
-
packages: use lowercase, group by function rather than scope
-
classes: should be nouns, in mixed case with the first letter of each internal word capitalized. Also known as
"PascalCase" or
"UpperCamelCase"-
interfaces: like classes
-
constants: should be all uppercase with words separated by underscores ("_").
-
methods: should describe actions or states, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. Also known as
"camelCase" or
"lowerCamelCase" . [
CONTROLVERSIAL] Use
strict camelCase (either UpperCamel or lowerCamel) for abbreviations.
-
variables: should be nouns, short yet meaningful, capitalized as "camelCase" . Should not start with '$' dollar-sign. [
CONTROVERSIAL] To
distinguish fields and other variables, use 1 underscore '_' as prefix for field names. [
CONTROVERSIAL] To
distinguish method parameters and other variables, use 1 underscore '_' as postfix for method parameters. [
CONTROVERSIAL] Should
not use "Hungarian" notation, use "postfix Object" instead. Example:
//import done
public class MyObject {
private String _objectName;
public String setObjectName(String objectName_) {
this._objectName = objectName_ ;
}
protected String downloadXmlThroughHttp(String xmlFileName_, URL httpUrl) {
//...
}
public static void main(String[] args_) {
public String objectName ; // don't use "strObjectName"
public String myMessage = args_[0]; // don't use "strMsg"
JTextArea commentTextArea; // don't use "txtComment"
protected JButton cancelButton; // don't use "btnCancel"
protected JButton saveButton; // don't use "btnSave"
private DataInputStream myDataIS; // don't use "dis"
private BufferedOutputStream myBufferedOS; // don't use "bufferedOutputStream"
//...
}
}
+
Miscellaneous recommendations:
- [
CONTROVERSIAL]
Open brace '{' appears at the end of the same line as the declaration statement. Also known as
"one true brace" .
- Each line should contain one statement, at most.
- Use braces for single-statement block (if, else, do, while, for, try, catch,... )
- Always have 1 space (at least) to seperate operator, casting, parameters from others.
- No space between a method name and the parenthesis '(' which starts the parameter list
- Try to initialize local variables where they’re declared
=== Reference ===+
Ontko's Java coding standard collections (including Sun's, Dough Lea's, ...)
+
Agile Java Development book, Appendix B
+
Java Power Tools book, part 6