General Programming Best Practices by Ahmet Haliloglu
|Program for people, not the machine. The primary goal of your development efforts should be that your code is easy for other people to understand. If no one else can figure it out, then it isnt any good. Use naming conventions. Document your code. Paragraph it.|
|Keep your code simple. Complex code might be intellectually satisfying to write but if other people cant understand it then it isnt any good. The first time that someone, perhaps even you, is asked to modify a piece of complex code to either fix a bug or to enhance it chances are pretty good that the code will get rewritten. In fact, youve probably even had to rewrite somebody elses code because it was too hard to understand. What did you think of the original developer when you rewrote their code, did you think that person was a genius or a jerk? Writing code that needs to be rewritten later is nothing to be proud of, so follow the KISS rule: Keep it simple, stupid.|
|Learn common patterns, antipatterns, and idioms. There is a wealth of analysis, design, and process patterns and antipatterns, as well as programming idioms, available to guide you in increasing your development productivity.|
|Avoid using magic numberswhich are numbers hard-wired into code. These are a nightmare if you need to change them, since you never know if 100 means the array size or something else entirely. Instead, create a constant with a descriptive name and use the constant identifier throughout your program. This makes the program easier to understand and much easier to maintain.|
|Remember that code is read much more than it is written.
Clean designs make for easy-to-understand programs, but comments, detailed explanations, and examples are invaluable. They will help both you and everyone who comes after you. If nothing else, the frustration of trying to ferret out useful information from the online Java documentation should convince you.
|Watch out for premature optimization. First make it work, then make it fastbut only if you must, and only if its proven that there is a performance bottleneck in a particular section of your code. Unless you have used a profiler to discover a bottleneck, you will probably be wasting your time. The hidden cost of performance tweaks is that your code becomes less understandable and maintainable.|
|Make code self documenting before commenting it
Try to make code as self document as possible before resorting to commenting it. This can both to improve the design and better describe an existing design than using comments. Specifications and code within a programming language are always more precise and useful than comments. If the code can describe itself better, this provides a constant reinforcement to future development (the clients and maintainers of this code). Comments are just auxiliary information and (although useful) should be a second choice.
|General Commenting Concepts:
· Comments should add to the clarity of your code
· If your program isnt worth documenting, it probably isnt worth running
· Avoid decoration, i.e. do not use banner-like comments
· Keep comments simple
· Write the documentation before you write the code
· Document why something is being done, not just what
|Provide comments that augment, not repeat, program code
Make comments augment, not repeat, information available in languagesyntax itself. Statements made in the programming language are precise, communicative, and guaranteed to be "true" (the program does what it says it does). If comments repeat information already specified they provide nothing and they are likely to become out of date and incorrect.