* 6. a professional programmer teaches by documentation; writing is hard but * the best software documentation has always been written by programmers * who were willing to make an extra effort
Sacha Chua puts it more succinctly:
A professional programmer best teaches by the source. No matter how good your documentation is, there is no substitute for the source code.
The source code is the reason why any proficient programmer can innovate on each others work. Documentation complements the source code. Source code can stand on its own, documentation alone cannot. This means that if you have source code and no documentation, you can still look at it and understand what it does. If you only have documentation and no source code, you'll waste much time reverse-engineering the whole thing.
This debate probably dates back to the date when the very first assemblers started supporting comments.
I don't intend to rant against self-documenting source code, BUT I must stress that
stand-alone documentation has its uses.
Consider a hypothetical software module implemented using static HTML docs, JSPs,
servlets, EJBs, and database triggers and stored procedures. Assume that the module
implements the Singleton pattern. Where will you document that you are using the Singleton pattern? In the JSP source? servlet source? EJB source? In all of them?
Radamanthus Batnag
-- Philippine Linux Users' Group (PLUG) Mailing List [EMAIL PROTECTED] (#PLUG @ irc.free.net.ph) Official Website: http://plug.linux.org.ph Searchable Archives: http://marc.free.net.ph . To leave, go to http://lists.q-linux.com/mailman/listinfo/plug . Are you a Linux newbie? To join the newbie list, go to http://lists.q-linux.com/mailman/listinfo/ph-linux-newbie
