Appendix A. Development tips for portable applications 307
sticking to the class and method contracts the developer is more likely to achieve
the desired outcome: a module that is going to pass Unit Test first time around.
Local comments best practice: why, not what
During coding, code should be commented where necessary. The comments we
are talking about in this case are not JavaDoc comments. They are local
comments written at some point in an algorithm inside a method body. The
general best practice rule of thumb for writing effective comments is that the
comments should explain 'Why?' and not 'What?'. Well-designed, well-written
code is itself a documentation of what is happening. If code is so poorly designed
or esoterically written that ...