A note on naming conventions. We recommend that you use pithy (single character if possible) yet evocative names for formal type parameters. It’s best to avoid lowercase characters in those names, making it easy to distinguish formal type parameters from ordinary classes and interfaces. Many container types use E, for element, as in the examples above.
Showing posts with label coding style. Show all posts
Showing posts with label coding style. Show all posts
Monday, 18 April 2011
Saturday, 12 March 2011
Avoid basic style errors
Many beginners to Java repeat the same basic style errors. Such style errors don't make your program incorrect, but they make your program less maintainable. In essence, many beginners write code that suffers from the same basic underlying defect of not being written with compassion for the reader.
There are in fact two target platforms for all code: the runtime hardware, and the human cerebral cortex. All code 'runs' in the human brain, in the sense that all code needs to be understood by a human being. Coding style is always concerned with this second target platform, not with the first.
Some common basic style errors :
There are in fact two target platforms for all code: the runtime hardware, and the human cerebral cortex. All code 'runs' in the human brain, in the sense that all code needs to be understood by a human being. Coding style is always concerned with this second target platform, not with the first.
Some common basic style errors :
- classes too long
- methods too long
- little or no javadoc
- no convention for distinguishing between local variables, arguments, and fields
- many empty catch blocks that suppress exceptions
- using exceptions to define regular program flow
- excessive use of the instanceof operator
- using floating point data to represent money
- preferring arrays over collections (especially in JDK 5+)
Some basic style errors are much more damaging to your code than others. The single most harmful bad habit is that of excessive length. Classes that are too long are hard to understand. As a guideline, if a class is more than about 300 lines long, you should likely consider splitting it up into smaller pieces. Similarly, methods that are more than a single screen are very likely too long, and would almost always benefit from being split into several methods.
Thursday, 16 September 2010
Common naming convention : Coding Style
Variable names must be in mixed case starting with lower case.
Common practice in the Java development community and also the naming convention for variables used by Sun for the Java core packages. Makes variables easy to distinguish from types, and effectively resolves potential naming collision as in the declaration
eg.
int state;
Names representing constants (final variables) must be all uppercase using underscore to separate words.
MAX_ITERATIONS, COLOR_RED
Common practice in the Java development community and also the naming convention used by Sun for the Java core packages.
In general, the use of such constants should be minimized. In many cases implementing the value as a method is a better choice:
int getMaxIterations() // NOT: MAX_ITERATIONS = 25
{
return 25;
}
This form is both easier to read, and it ensures a uniform interface towards class values.
Names representing methods must be verbs and written in mixed case starting with lower case. getName(), computeTotalWidth()
Abbreviations and acronyms should not be uppercase when used as name.
exportHtmlSource(); // NOT: exportHTMLSource();
openDvdPlayer(); // NOT: openDVDPlayer();
Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type whould have to be named dVD, hTML etc. which obviously is not very readable. Another problem is illustrated in the examples above; When the name is connected to another, the readability is seriously reduced; The word following the acronym does not stand out as it should.
Private class variables should have underscore suffix.
A side effect of the underscore naming convention is that it nicely resolves the problem of finding reasonable variable names for setter methods:
An issue is whether the underscore should be added as a prefix or as a suffix. Both practices are commonly used, but the latter is recommended because it seem to best preserve the readability of the name.
It should be noted that scope identification in variables have been a controversial issue for quite some time. It seems, though, that this practice now is gaining acceptance and that it is becoming more and more common as a convention in the professional development community.
Generic variables should have the same name as their type.
If for some reason this convention doesn't seem to fit it is a strong indication that the type name is badly chosen.
Non-generic variables have a role. These variables can often be named by combining role and type:
Point startingPoint, centerPoint;
Name loginName;
All names should be written in English.English is the preferred language for international development.
Variables with a large scope should have long names, variables with a small scope can have short names
Scratch variables used for temporary storage or indices are best kept short. A programmer reading such variables should be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.
The name of the object is implicit, and should be avoided in a method name.
The terms get/set must be used where an attribute is accessed directly.
is prefix should be used for boolean variables and methods.
Using the is prefix solves a common problem of choosing bad boolean names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to chose more meaningful names.
Setter methods for boolean variables must have set prefix as in:
There are a few alternatives to the is prefix that fits better in some situations. These are has, can and should prefixes:
boolean hasLicense();
boolean canEvaluate();
boolean shouldAbort = false;
The term compute can be used in methods where something is computed.
Iterator variables should be called i, j, k etc.
for (Iterator i = points.iterator(); i.hasNext(); ) { : } for (int i = 0; i < nTables; i++) { : }
The notation is taken from mathematics where it is an established convention for indicating iterators. Variables named j, k etc. should be used for nested loops only.
Complement names must be used for complement entities
get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, first/last, up/down, min/max, next/previous, old/new, open/close, show/hide, suspend/resume, etc.
Reduce complexity by symmetry.
Abbreviations in names should be avoided.
computeAverage(); // NOT: compAvg();
ActionEvent event; // NOT: ActionEvent e;
catch (Exception exception) { // NOT: catch (Exception e) {
There are two types of words to consider. First are the common words listed in a language dictionary. These must never be abbreviated.
Never write:
cmd instead of command comp instead of compute cp instead of copy e instead of exception init instead of initialize pt instead of point etc. Then there are domain specific phrases that are more naturally known through their acronym or abbreviations. These phrases should be kept abbreviated. Never write: HypertextMarkupLanguage instead of html CentralProcessingUnit instead of cpu PriceEarningRatio instead of pe etc.
Negated boolean variable names must be avoided.
bool isError; // NOT: isNoError
bool isFound; // NOT: isNotFound
The problem arise when the logical not operator is used and double negative arises. It is not immediately apparent what !isNotError means.
Associated constants (final variables) should be prefixed by a common type name.
final int COLOR_RED = 1; final int COLOR_GREEN = 2; final int COLOR_BLUE = 3; This indicates that the constants belong together, and what concept the constants represents.
An alternative to this approach is to put the constants inside an interface effectively prefixing their names with the name of the interface: interface Color { final int RED = 1; final int GREEN = 2; final int BLUE = 3; }
Exception classes should be suffixed with Exception.
class AccessException extends Exception { : } Exception classes are really not part of the main design of the program, and naming them like this makes them stand out relative to the other classes. This standard is followed by Sun in the basic Java library.
Default interface implementations can be prefixed by Default.
class DefaultTableCellRenderer implements TableCellRenderer { : } It is not uncommon to create a simplistic class implementation of an interface providing default behaviour to the interface methods. The convention of prefixing these classes by Default has been adopted by Sun for the Java library.
Singleton classes should return their sole instance through method getInstance.
class UnitManager { private final static UnitManager instance_ = new UnitManager(); private UnitManager() { ... } public static UnitManager getInstance() // NOT: get() or instance() or unitManager() etc. { return instance_; } } Common practice in the Java community though not consistently followed by Sun in the JDK. The above layout is the preferred pattern.
Classes that creates instances on behalf of others (factories) can do so through method new[ClassName]
class PointFactory { public Point newPoint(...) { ... } }
Indicates that the instance is created by new inside the factory method and that the construct is a controlled replacement of new Point().
Functions (methods returning an object) should be named after what they return and procedures (void methods) after what they do. Increase readability. Makes it clear what the unit should do and especially all the things it is not supposed to do. This again makes it easier to keep the code clean of side effects. 4 Files
Classes should be declared in individual files with the file name matching the class name.
Secondary private classes can be declared as inner classes and reside in the file of the class they belong to. Enforced by the Java tools.
File content must be kept within 80 columns. 80 columns is the common dimension for editors, terminal emulators, printers and debuggers, and files that are shared between several developers should keep within these constraints. It improves readability when unintentional line breaks are avoided when passing a file between programmers.
Special characters like TAB and page break must be avoided.
These characters are bound to cause problem for editors, printers, terminal emulators or debuggers when used in a multi-programmer, multi-platform environment.
The incompleteness of split lines must be made obvious
totalSum = a + b + c +
d + e;
method(param1, param2,
param3);
setText ("Long line split" +
"into two parts.");
for (int tableNo = 0; tableNo < nTables;
tableNo += tableStep) { ... }
Split lines occurs when a statement exceed the 80 column limit given above. It is difficult to give rigid rules for how lines should be split, but the examples above should give a general hint. In general:
Break after a comma.
Break after an operator.
Align the new line with the beginning of the expression on the previous line. 5 Statements
Type conversions must always be done explicitly. Never rely on implicit type conversion.
floatValue = (int) intValue; // NOT: floatValue = intValue;
By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional.
Variables should be initialized where they are declared and they should be declared in the smallest scope possible.
This ensures that variables are valid at any time. Sometimes it is impossible to initialize a variable to a valid value where it is declared. In these cases it should be left uninitialized rather than initialized to some phony value.
Common practice in the Java development community and also the naming convention for variables used by Sun for the Java core packages. Makes variables easy to distinguish from types, and effectively resolves potential naming collision as in the declaration
eg.
int state;
Names representing constants (final variables) must be all uppercase using underscore to separate words.
MAX_ITERATIONS, COLOR_RED
Common practice in the Java development community and also the naming convention used by Sun for the Java core packages.
In general, the use of such constants should be minimized. In many cases implementing the value as a method is a better choice:
int getMaxIterations() // NOT: MAX_ITERATIONS = 25
{
return 25;
}
This form is both easier to read, and it ensures a uniform interface towards class values.
Names representing methods must be verbs and written in mixed case starting with lower case. getName(), computeTotalWidth()
Abbreviations and acronyms should not be uppercase when used as name.
exportHtmlSource(); // NOT: exportHTMLSource();
openDvdPlayer(); // NOT: openDVDPlayer();
Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type whould have to be named dVD, hTML etc. which obviously is not very readable. Another problem is illustrated in the examples above; When the name is connected to another, the readability is seriously reduced; The word following the acronym does not stand out as it should.
Private class variables should have underscore suffix.
class Person {
private String name_;
... }
Apart from its name and its type, the scope of a variable is its most important feature. Indicating class scope by using underscore makes it easy to distinguish class variables from local scratch variables. This is important because class variables are considered to have higher significance than method variables, and should be treated with special care by the programmer.A side effect of the underscore naming convention is that it nicely resolves the problem of finding reasonable variable names for setter methods:
void setName(String name)
{
name_ = name;
}
An issue is whether the underscore should be added as a prefix or as a suffix. Both practices are commonly used, but the latter is recommended because it seem to best preserve the readability of the name.
It should be noted that scope identification in variables have been a controversial issue for quite some time. It seems, though, that this practice now is gaining acceptance and that it is becoming more and more common as a convention in the professional development community.
Generic variables should have the same name as their type.
void setTopic(Topic topic) // NOT: void setTopic(Topic value)
// NOT: void setTopic(Topic aTopic)
// NOT: void setTopic(Topic t)
void connect(Database database) // NOT: void connect(Database db)
// NOT: void connect(Database oracleDB)
Reduce complexity by reducing the number of terms and names used. Also makes it easy to deduce the type given a variable name only.If for some reason this convention doesn't seem to fit it is a strong indication that the type name is badly chosen.
Non-generic variables have a role. These variables can often be named by combining role and type:
Point startingPoint, centerPoint;
Name loginName;
All names should be written in English.English is the preferred language for international development.
Variables with a large scope should have long names, variables with a small scope can have short names
Scratch variables used for temporary storage or indices are best kept short. A programmer reading such variables should be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.
The name of the object is implicit, and should be avoided in a method name.
line.getLength(); // NOT: line.getLineLength();
The latter might seem natural in the class declaration, but proves superfluous in use, as shown in the example.The terms get/set must be used where an attribute is accessed directly.
employee.getName();
employee.setName(name);
matrix.getElement(2, 4);
matrix.setElement(2, 4, value);
is prefix should be used for boolean variables and methods.
isSet, isVisible, isFinished, isFound, isOpen
This is the naming convention for boolean methods and variables used by Sun for the Java core packages.Using the is prefix solves a common problem of choosing bad boolean names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to chose more meaningful names.
Setter methods for boolean variables must have set prefix as in:
void setFound(boolean isFound);
There are a few alternatives to the is prefix that fits better in some situations. These are has, can and should prefixes:
boolean hasLicense();
boolean canEvaluate();
boolean shouldAbort = false;
The term compute can be used in methods where something is computed.
valueSet.computeAverage(); matrix.computeInverse()
Give the reader the immediate clue that this is a potential time consuming operation, and if used repeatedly, he might consider caching the result. Consistent use of the term enhances readability.Iterator variables should be called i, j, k etc.
for (Iterator i = points.iterator(); i.hasNext(); ) { : } for (int i = 0; i < nTables; i++) { : }
Associated constants (final variables) should be prefixed by a common type name.
Exception classes should be suffixed with Exception.
Default interface implementations can be prefixed by Default.
Singleton classes should return their sole instance through method getInstance.
Classes that creates instances on behalf of others (factories) can do so through method new[ClassName]
Functions (methods returning an object) should be named after what they return and procedures (void methods) after what they do. Increase readability. Makes it clear what the unit should do and especially all the things it is not supposed to do. This again makes it easier to keep the code clean of side effects. 4 Files
Classes should be declared in individual files with the file name matching the class name.
File content must be kept within 80 columns. 80 columns is the common dimension for editors, terminal emulators, printers and debuggers, and files that are shared between several developers should keep within these constraints. It improves readability when unintentional line breaks are avoided when passing a file between programmers.
Special characters like TAB and page break must be avoided.
Type conversions must always be done explicitly. Never rely on implicit type conversion.
floatValue = (int) intValue; // NOT: floatValue = intValue;
By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional.
This ensures that variables are valid at any time. Sometimes it is impossible to initialize a variable to a valid value where it is declared. In these cases it should be left uninitialized rather than initialized to some phony value.
Improving coding style into classes
Class and Interface declarations should be organized in the following manner:
1. Class/Interface documentation.
2. class or interface statement.
3. Class (static) variables in the order public, protected, package (no access modifier), private.
4. Instance variables in the order public, protected, package (no access modifier), private.
5. Constructors.
6. Methods (no specific order). Reduce complexity by making the location of each class element predictable.
Imported classes should always be listed explicitly.
import java.util.List; // NOT: import java.util.*;
import java.util.ArrayList;
import java.util.HashSet;
Importing classes explicitly gives an excellent documentation value for the class at hand and makes the class easier to comprehend and maintain. Appropriate tools should be used in order to always keep the import list minimal and up to date.
Imported classes should always be listed explicitly.
Importing classes explicitly gives an excellent documentation value for the class at hand and makes the class easier to comprehend and maintain. Appropriate tools should be used in order to always keep the import list minimal and up to date.
Improving coding style into functions or methods
Method modifiers should be given in the following order: static abstract synchronized final native
The modifier (if present) must be the first modifier.
public static double square(double a); // NOT: static public double square(double a);
is one of public, protected or private while includes volatile and transient. The most important lesson here is to keep the access modifier as the first modifier. Of the possible modifiers, this is by far the most important, and it must stand out in the method declaration. For the other modifiers, the order is less important, but it make sense to have a fixed convention.
The
public static double square(double a);
is one of public, protected or private while includes volatile and transient. The most important lesson here is to keep the access modifier as the first modifier. Of the possible modifiers, this is by far the most important, and it must stand out in the method declaration. For the other modifiers, the order is less important, but it make sense to have a fixed convention.
Specific cases of naming enhancing naming style
The term find can be used in methods where something is looked up.
The term initialize can be used where an object or a concept is established.
Plural form should be used on names representing a collection of objects.
Collection points; int[] values;
Enhances readability since the name gives the user an immediate clue of the type of the variable and the operations that can be performed on its elements.
n prefix should be used for variables representing a number of objects.
nPoints, nLines
The notation is taken from mathematics where it is an established convention for indicating a number of objects.
Note that Sun use num prefix in the core Java packages for such variables. This is probably meant as an abbreviation of number of, but as it looks more like number it makes the variable name strange and misleading. If "number of" is the preferred phrase, numberOf prefix can be used instead of just n. num prefix must not be used.
No suffix should be used for variables representing an entity number.
tableNo, employeeNo
The notation is taken from mathematics where it is an established convention for indicating an entity number.
An elegant alternative is to prefix such variables with an i: iTable, iEmployee. This effectively makes them named iterators.
vertex.findNearestVertex(); matrix.findSmallestElement(); node.findShortestPath(Node destinationNode);
Give the reader the immediate clue that this is a simple look up method with a minimum of computations involved. Consistent use of the term enhances readability.The term initialize can be used where an object or a concept is established.
printer.initializeFontSet();
The American initializeshould be preferred over the English initialise. Abbreviation init must be avoided.Plural form should be used on names representing a collection of objects.
Collection
Enhances readability since the name gives the user an immediate clue of the type of the variable and the operations that can be performed on its elements.
n prefix should be used for variables representing a number of objects.
nPoints, nLines
The notation is taken from mathematics where it is an established convention for indicating a number of objects.
Note that Sun use num prefix in the core Java packages for such variables. This is probably meant as an abbreviation of number of, but as it looks more like number it makes the variable name strange and misleading. If "number of" is the preferred phrase, numberOf prefix can be used instead of just n. num prefix must not be used.
No suffix should be used for variables representing an entity number.
tableNo, employeeNo
The notation is taken from mathematics where it is an established convention for indicating an entity number.
An elegant alternative is to prefix such variables with an i: iTable, iEmployee. This effectively makes them named iterators.
Java specific naming convention
JFC (Java Swing) variables should be suffixed by the element type.
widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog
Enhances readability since the name gives the user an immediate clue of the type of the variable and thereby the available resources of the object.
Array specifiers must be attached to the type not the variable.
int[] a = new int[20]; // NOT: int a[] = new int[20]
The arrayness is a feature of the base type, not the variable. It is not known why Sun allows both forms.
Java source files should have the extension .java. Point.java Enforced by the Java tools.
The import statements must follow the package statement. import statements should be sorted with the most fundamental packages first, and grouped with associated packages together and one blank line between groups.
The package statement must be the first statement of the file.
All files should belong to a specific package. The package statement location is enforced by the Java language. Letting all files belong to an actual (rather than the Java default) package enforces Java language object oriented programming techniques.
widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog
Enhances readability since the name gives the user an immediate clue of the type of the variable and thereby the available resources of the object.
Array specifiers must be attached to the type not the variable.
int[] a = new int[20]; // NOT: int a[] = new int[20]
The arrayness is a feature of the base type, not the variable. It is not known why Sun allows both forms.
Java source files should have the extension .java. Point.java Enforced by the Java tools.
The import statements must follow the package statement. import statements should be sorted with the most fundamental packages first, and grouped with associated packages together and one blank line between groups.
import java.io.IOException;
import java.net.URL;
import java.rmi.RmiServer;
import java.rmi.server.Server;
import javax.swing.JPanel;
import javax.swing.event.ActionEvent;
import org.linux.apache.server.SoapServer;
The import statement location is enforced by the Java language. The sorting makes it simple to browse the list when there are many imports, and it makes it easy to determine the dependiencies of the present package The grouping reduce complexity by collapsing related information into a common unit.The package statement must be the first statement of the file.
All files should belong to a specific package. The package statement location is enforced by the Java language. Letting all files belong to an actual (rather than the Java default) package enforces Java language object oriented programming techniques.
Subscribe to:
Posts (Atom)