Coding Standards for Java
These standards are published in The Elements of Java Style by Allan Vermeulen, Scott Ambler, Greg Bumgardner, Eldon Metz, Trevor Misfeldt, Jim Shur and Patrick Thompson; published by Cambridge University Press 2000 ISBN 0 521 777682.
Ian Mitchell recommends this book and has emailed the publisher requesting permission to use the material.
General Principles
1. Adhere to the style of the original.
2. Adhere to the Principle of Least Astonishment.
3. Do it right first time.
4. Document any deviation. Top
Formatting Conventions
5. Indent nested code.
6. Break up long lines.
7. Include white space.
8. Do not use “hard” tabs. Top
Naming Conventions
9. Use meaningful names.
10. Use familiar names.
11. Question exceptionally long names.
12. Join the vowel generation.
13. Capitalise only the first letter in acronyms.
14. Do not use names that differ only in case. Top
Package Names
15. Use the reversed, lowercase form of your organization’s Internet domain name as the root qualifier for your package names.
16. Use a single, lowercase word as the root name of each package.
17. Use the same name for a new version of a package, but only if that new version is still binary compatible with the previous version, otherwise, use a new name. Top
Type Names
18. Capitalize the first letter of each word that appears in a class or interface name. Top
Class Names
19. Use nouns when naming classes.
20. Pluralize the names of classes that group related attributes, static services, or constants. Top
Interface Names
21. Use nouns or adjectives when naming interfaces. Top
Method Names
22. Use lowercase for the first word and capitalize only the first letter of each subsequent word that appears in a method name.
23. Use verbs when naming methods.
24. Follow the JavaBeans conventions for naming property accessor methods. Top
Variable Names
25. Use lowercase for the first word and capitalize only the first letter of each subsequent word that appears in a variable name.
26. Use nouns to name variables.
27. Pluralize the names of collection references.
28. Establish and use a set of standard names for trivial “throwaway” variables. Top
Field Names
29. Qualify field variables with ?this” to distinguish them from local variables. Top
Parameter Names
30. When a constructor or ?set? method assigns a parameter to a field, give that parameter the same name as the field. Top
Constant Names
31. Use uppercase letters for each word and separate each pair of words with an underscore when naming constants. Top
Documentation Conventions
32. Write documentation for those who must use your code and those who must maintain it.
33. Keep comments and code in sync.
34. Use the active voice and omit needless words. Top
Comment Types
35. Use documentation comments to describe the programming interface.
36. Use standard comments to hide code without removing it.
37. Use one-line comments to explain implementation details. Top
Documentation Comments
38. Describe the programming interface before you write the code.
39. Document public, protected, package and private members.
40. Provide a summary description and overview for each package.
41. Provide a summary description and overview for each application or group of packages. Top
Comment Style
42. Use a single consistent format and organization for all documentation comments.
43. Wrap keywords, identifiers, and constants with <code> . . . </code> tags.
44. Wrap code with <pre> . . . </pre> tags.
45. Consider marking the first occurrence of an identifier with a {@link} tag.
46. Establish and use a fixed ordering for Javadoc tags.
47. Write in the third-person narrative form.
48. Write summary descriptions that stand alone.
49. Omit the subject in summary descriptions of actions or services.
50. Omit the subject and the verb in summary descriptions of things.
51. Use “this” rather than “the” referring to instances of the current class.
52. Do not add parentheses to a method or constructor name unless you want to specify a particular signature. Top
Comment Content
53. Provide a summary description for each class, interface, field, and method.
54. Fully describe the signature of each method.
55. Include examples.
56. Document pre-conditions, post-conditions, and invariant conditions.
57. Document known defects and deficiencies.
58. Document synchronization semantics. Top
Internal Comments
59. Add internal comments only if they will aid others in understanding your code.
60. Describe why the code is doing what it does, not what the code is doing.
61. Avoid the use of end-line comments.
62. Explain local variable declarations with an end-line comment.
63. Establish and use a set of keywords to flag unresolved issues.
64. Label closing braces in highly nested control structures.
65. Add a “fall-through” comment between two case labels, if no break statement separates those labels.
66. Label empty statements. Top
Programming Conventions
67. Consider declaring classes representing fundamental data types as final.
68. Build concrete types from native types and other concrete types.
69. Define small classes and small methods.
70. Define subclasses so they may be used anywhere their superclass may be used.
71. Make all fields private.
72. Use polymorphism instead of instanceof. Top
Type Safety
73. Wrap general-purpose classes that operate on java.lang.Object to provide static type checking.
74. Encapsulate enumerations as classes. Top
Statements and Expressions
75. Replace repeated nontrivial expressions with equivalent methods.
76. Use block statements instead of expression statements in control flow constructs.
77. Clarify the order of operations with parentheses.
78. Always code a break statement in the last case of a switch statement.
79. Use equals(), not ==, to test for equality of objects. Top
Construction
80. Always construct objects in a valid state.
81. Do not call nonfinal methods from within a constructor.
82. Use nested constructors to eliminate redundant code. Top
Exception Handling
83. Use unchecked, run-time exceptions to report serious unexpected errors that may indicate an error in the program?s logic.
84. Use checked exceptions to report errors that may occur, however rarely, under normal program operation.
85. Use return codes to report expected state changes.
86. Only convert exceptions to add information.
87. Do not silently absorb a run-time or error exception.
88. Use a finally block to release resources. Top
Assertions
89. Program by contract.
90. Use dead code elimination to implement assertions.
91. Use assertions to catch logic errors in your code.
92. Use assertions to test pre- and post-conditions of a method. Top
Concurrency
93. Use threads only where appropriate. Top
Synchronization
94. Avoid synchronization.
95. Use synchronized wrappers to provide synchronized interfaces.
96. Do not synchronize an entire method if the method contains significant operations that do not need synchronization.
97. Avoid unnecessary synchronization when reading or writing instance variables.
98. Consider using notify() instead of notifyAll().
99. Use the double-check pattern for synchronized initialization. Top
Efficiency
100. Use lazy initialisation.
101. Avoid creating unnecessary objects.
102. Re-initialize and reuse objects to avoid new object construction.
103. Leave optimisation for last. Top
Packaging Conventions
104. Place types that are commonly used, changed, and released together, or mutually dependent on each other, into the same package.- The Common Reuse Principle
- The Common Closure Principle
- The Reuse/Release Equivalence Principle
- The Acyclic Dependencies Principle
105. Isolate volatile classes and interfaces in separate packages.
106. Avoid making packages that are difficult to change dependent on packages that are easy to change.
107. Maximize abstraction to maximize stability.
108. Capture high-level design and architecture as stable abstractions organized into stable packages.
Top
