Mantras

[This article is going to be extended every now and then]

All Redundancy Is Evil

Really, if you can avoid redundancy, do it. If it costs some unpleasant effort, bear it - you'll get repaid later again and again.

Copy and paste is a surefire way to pain and suffering. It is very hard to see if different but similar code really does the same thing - you'll have to compare the two spots down to the last character. And when there are differences, are they the result of deliberate modification or some accidentally incomplete update?

If it can be generated, don't check in the product but polish the source (and, if necessary, the generator and/ or its configuration) and automatize the process. There are way too many projects where the results of some generator run have been checked in. After a few months nobody can tell for sure anymore whether the generated stuff has been modified by hand (and don't do that).

Don't "Unstructure" Information

Enterprise Architect, a very good UML modelling tool, allows you to attach RTF documents to an UML element (the tech term is "linked document"). I've seen projects where all information is in the RTF document, and none in the fields and links that Enterprise Architect generously provides (pre- and postconditions, scenarios, actors etc.).

Why in the world anybody would do something like that is beyond me - you loose all opportunities to generate reports (ensuring a standard look and feel), run crosschecks, enforce documentation standards, perform context-specific searches, visualize dependencies, trace relationships, access information via an API and much more.