Progamming style guidelines

http://home.earthlink.net/~huston2/books/programming_books.html

 

The Practice of Programming
Brian Kernighan, Rob Pike

Style

1. Use descriptive names for globals, short names for locals.
2. Be consistent.
3. Use active names for functions.
4. Be accurate.
5. Indent to show structure.
6. Use the natural form for expressions.
7. Parenthesize to resolve ambiguity.
8. Break up complex expressions.
9. Be clear.
10. Be careful with side effects.
11. Use a consistent indentation and brace style.
12. Use idioms for consistency.
13. Use else-ifs for multi-way decisions.
14. Avoid function macros.
15. Parenthesize the macro body and arguments.
16. Give names to magic numbers.
17. Define numbers as constants, not macros.
18. Use character constants, not integers.
19. Use the language to calculate the size of an object.
20. Don't belabor the obvious.
21. Comment functions and global data.
22. Don't comment bad code, rewrite it.
23. Don't contradict the code. Clarify, don't confuse.

Interfaces

24. Hide implementation details.
25. Choose a small orthogonal set of primitives.
26. Don't reach behind the user's back.
27. Do the same thing the same way everywhere.
28. Free a resource in the same layer that allocated it.
29. Detect errors at a low level, handle them at a high level.
30. Use exceptions only for exceptional situations.

Debugging

31. Look for familiar patterns.
32. Examine the most recent change.
33. Don't make the same mistake twice.
34. Debug it now, not later.
35. Get a stack trace.
36. Read before typing.
37. Explain your code to someone else.
38. Make the bug reproducible.
39. Divide and conquer.
40. Study the numerology of failures.
41. Display output to localize your search.
42. Write self-checking code.
43. Write a log file.
44. Draw a picture.
45. Use tools.
46. Keep records.

Testing

47. Test code at its boundaries.
48. Test pre- and post-conditions.
49. Use assertions.
50. Program defensively.
51. Check error returns.
52. Test incrementally.
53. Test simple parts first.
54. Know what output to expect.
55. Verify conservation properties.
56. Compare independent implementations.
57. Measure test coverage.
58. Automate regression testing.
59. Create self-contained tests.

Performance

60. Automate timing measurements.
61. Use a profiler.
62. Concentrate on the hot spots.
63. Draw a picture.
64. Use a better algorithm or data structure.
65. Enable compiler optimizations.
66. Tune the code.
67. Don't optimize what doesn't matter.
68. Collect common subexpressions.
69. Replace expensive operations by cheap ones.
70. Unroll or eliminate loops.
71. Cache frequently-used values.
72. Write a special-purpose allocator.
73. Buffer input and output.
74. Handle special cases separately.
75. Precompute results.
76. Use approximate values.
77. Rewrite in a lower-level language.
78. Save space by using the smallest possible data type.
79. Don't store what you can easily recompute.

Portability

80. Stick to the standard.
81. Program in the mainstream.
82. Beware of language trouble spots.
83. Try several compilers.
84. Use standard libraries.
85. Use only features available everywhere.
86. Avoid conditional compilation.
87. Localize system dependencies in separate files.
88. Hide system dependencies behind interfaces.
89. Use text for data exchange.
90. Use a fixed byte order for data exchange.
91. Change the name if you change the specification.
92. Maintain compatibility with existing programs and data.
93. Don't assume ASCII.
94. Don't assume English.

 

 

The Elements of Programming Style
Brian Kernighan, P. J. Plauger

Introduction

1. Write clearly - don't be too clever.

Expression

2. Say what you mean, simply and directly.
3. Use library functions.
4. Avoid temporary variables.
5. Write clearly - don't sacrifice clarity for "efficiency."
6. Let the machine do the dirty work.
7. Replace repetitive expressions by calls to a common function.
8. Parenthesize to avoid ambiguity.
9. Choose variable names that won't be confused.
10. Avoid the Fortran arithmetic IF.
11. Avoid unnecessary branches.
12. Use the good features of a language; avoid the bad ones.
13. Don't use conditional branches as a substitute for a logical expression.
14. Use the "telephone test" for readability.

Control Structure

15. Use DO-END and indenting to delimit groups of statements.
16. Use IF-ELSE to emphasize that only one of two actions is to be performed.
17. Use DO and DO-WHILE to emphasize the presence of loops.
18. Make your programs read from top to bottom.
19. Use IF, ELSE IF, ELSE IF, ELSE to implement multi-way branches.
20. Use the fundamental control flow constructs.
21. Write first in an easy-to-understand pseudo-language; then translate into whatever language you have to use.
22. Avoid THEN-IF and null ELSE.
23. Avoid ELSE GOTO and ELSE RETURN.
24. Follow each decision as closely as possible with its associated action.
25. Use data arrays to avoid repetitive control sequences.
26. Choose a data representation that makes the program simple.
27. Don't stop with your first draft.

Program Structure

28. Modularize. Use subroutines.
29. Make the coupling between modules visible.
30. Each module should do one thing well.
31. Make sure every module hides something.
32. Let the data structure the program.
33. Don't patch bad code ?rewrite it.
34. Write and test a big program in small pieces.
35. Use recursive procedures for recursively-defined data structures.

Input and Output

36. Test input for validity and plausibility.
37. Make sure input cannot violate the limits of the program.
38. Terminate input by end-of-file or marker, not by count.
39. Identify bad input; recover if possible.
40. Treat end of file conditions in a uniform manner.
41. Make input easy to prepare and output self-explanatory.
42. Use uniform input formats.
43. Make input easy to proofread.
44. Use free-form input when possible.
45. Use self-identifying input. Allow defaults. Echo both on output.
46. Localize input and output in subroutines.

Common Blunders

47. Make sure all variables are initialized before use.
48. Don't stop at one bug.
49. Use debugging compilers.
50. Initialize constants with DATA statements or INITIAL attributes; initialize variables with executable code.
51. Watch out for off-by-one errors.
52. Take care to branch the right way on equality.
53. Avoid multiple exits from loops.
54. Make sure your code "does nothing" gracefully.
55. Test programs at their boundary values.
56. Program defensively.
57. 10.0 times 0.1 is hardly ever 1.0.
58. Don't compare floating point numbers just for equality.

Efficiency and Instrumentation

59. Make it right before you make it faster.
60. Keep it right when you make it faster.
61. Make it clear before you make it faster.
62. Don't sacrifice clarity for small gains in "efficiency."
63. Let your compiler do the simple optimizations.
64. Don't strain to re-use code; reorganize instead.
65. Make sure special cases are truly special.
66. Keep it simple to make it faster.
67. Don't diddle code to make it faster ?find a better algorithm.
68. Instrument your programs. Measure before making "efficiency" changes.

Documentation

69. Make sure comments and code agree.
70. Don't just echo the code with comments ?make every comment count.
71. Don't comment bad code ?rewrite it.
72. Use variable names that mean something.
73. Use statement labels that mean something.
74. Format a program to help the reader understand it.
75. Indent to show the logical structure of a program.
76. Document your data layouts.
77. Don't over-comment.

 

Practical Java
Peter Haggar

General Techniques

1. Understand that parameters are passed by value, not by reference.
2. Use final for constant data and constant object references.
3. Understand that all non-static methods can be overridden by default.
4. Choose carefully between arrays and Vectors.
5. Prefer polymorphism to instanceof.
6. Use instanceof only when you must.
7. Set object references to null when they are no longer needed.

Objects and Equality

8. Differentiate between reference and primitive types.
9. Differentiate between == and equals.
10. Do not rely on the default implementation of equals.
11. Implement the equals method judiciously.
12. Prefer getClass in equals method implementations.
13. Call super.equals of base classes.
14. Consider carefully instance of in equals method implementations.
15. Follow these rules when implementing an equals method.

Exception handling

16. Know the mechanics of exception control flow.
17. Never ignore an exception.
18. Never hide an exception.
19. Consider the drawback to the throws clause.
20. Be specific and comprehensive with the throws clause.
21. Use finally to avoid resource leaks.
22. Do not return from a try block.
23. Place try/catch blocks outside of loops.
24. Do not use exceptions for control flow.
25. Do not use exceptions for every error condition.
26. Throw exceptions from constructors.
27. Return objects to a valid state before throwing an exception.

Performance

28. Focus initially on design, data structures, and algorithms.
29. Do not rely on compile-time code optimization.
30. Understand runtime code optimization.
31. Use StringBuffer, rather than String, for concatenation.
32. Minimize the cost of object creation.
33. Guard against unused objects.
34. Minimize synchronization.
35. Use stack variables whenever possible.
36. Use static, final, and private methods to allow in lining.
37. Initialize instance variables only once.
38. Use primitive types for faster and smaller code.
39. Do not use an Enumeration or an Iterator to traverse a Vector.
40. Use System array copy for copying arrays.
41. Prefer an array to a Vector or ArrayList.
42. Reuse objects whenever possible.
43. Use lazy evaluation.
44. Optimize source code by hand.
45. Compile to native code.

Multithreading

46. Understand that for instance methods, synchronized locks objects, not methods or code.
47. Distinguish between synchronized statics and synchronized instance methods.
48. Use private data with an accessor method instead of public or protected data.
49. Avoid unnecessary synchronization.
50. Use synchronized or volatile when accessing shared variables.
51. Lock all objects involved in a single operation.
52. Acquire multiple locks in a fixed, global order to avoid deadlock.
53. Prefer notifyAll to notify.
54. Use spin locks for wait and notifyAll.
55. Use wait and notifyAll instead of polling loops.
56. Do not reassign the object reference of a locked object.
57. Do not invoke the stop or suspend methods.
58. Terminate threads through thread cooperation.

Classes and Interfaces

59. Use interfaces to support multiple inheritance.
60. Avoid method clashes in interfaces.
61. Use abstract classes when it makes sense to provide a partial implementation.
62. Differentiate between an interface, abstract class, and concrete class.
63. Define and implement immutable classes judiciously.
64. Use clone for immutable objects when passing or receiving object references to mutable objects.
65. Use inheritance or delegation to define immutable classes.
66. Call super.clone when implementing a clone method.
67. Do not rely on finalize methods for non-memory resource cleanup.
68. Use care when calling non-final methods from constructors.

 

Effective Java
Joshua Bloch

Creating and Destroying Objects

1. Consider providing static factory methods instead of constructors
2. Enforce the singleton property with a private constructor
3. Enforce noninstantiability with a private constructor
4. Avoid creating duplicate objects
5. Eliminate obsolete object references
6. Avoid finalizers

Methods Common to All Objects

7. Obey the general contract when overriding equals
8. Always override hashCode when you override equals
9. Always override toString
10. Override clone judiciously
11. Consider implementing Comparable

Classes and Interfaces

12. Minimize the accessibility of classes and members
13. Favor immutability
14. Favor composition over inheritance
15. Design and document for inheritance or else prohibit it
16. Prefer interfaces to abstract classes
17. Use interfaces only to define types
18. Favor static member classes over nonstatic

Substitutes for C Constructs

19. Replace structures with classes
20. Replace unions with class hierarchies
21. Replace enum constructs with classes
22. Replace function pointers with classes and interfaces

Methods

23. Check parameters for validity
24. Make defensive copies when needed
25. Design method signatures carefully
26. Use overloading judiciously
27. Return zero-length arrays, not nulls
28. Write doc comments for all exposed API elements

General Programming

29. Minimize the scope of local variables
30. Know and use the libraries
31. Avoid float and double if exact answers are required
32. Avoid strings where other types are more appropriate
33. Beware the performance of string concatenation
34. Refer to objects by their interfaces
35. Prefer interfaces to reflection
36. Use native methods judiciously
37. Optimize judiciously
38. Adhere to generally accepted naming conventions

Exceptions

39. Use exceptions only for exceptional conditions
40. Use checked exceptions for recoverable conditions and run-time exceptions for programming errors
41. Avoid unnecessary use of checked exceptions
42. Favor the use of standard exceptions
43. Throw exceptions appropriate to the abstraction
44. Document all exceptions thrown by each method
45. Include failure-capture information in detail messages
46. Strive for failure atomicity
47. Don't ignore exceptions

Threads

48. Synchronize access to shared mutable data
49. Avoid excessive synchronization
50. Never invoke wait outside a loop
51. Don't depend on the thread scheduler
52. Document thread safety
53. Avoid thread groups

Serialization

54. Implement Serializable judiciously
55. Consider using a custom serialized form
56. Write readObject methods defensively
57. Provide a readResolve method when necessary