Good idea, Adam. Your list of goals triggered the thought -- why do we need documentation at all? Well, it's to communicate something useful that otherwise is not being communicated. I'm thinking specifically about the MifOS application and its code base. As I browse certain parts of it, I constantly feel the need for some kind of documentation because the code itself is not communicating to me what it does or why it does it (and therefore how to fix or enhance it).
The best solution is not to write lots of comments saying what it does and why, but instead to write INTENTION-REVEALING-CODE at the outset. Guidelines for doing so range from the simple (use meaningful names for variables, methods, classes) to the larger-grained (use well-thought-out interfaces, write short, coherent methods, design a class or method to do one and only one thing). If the designer/coder follows these guidelines, there's often little need for additional documentation. At a larger grain, employing well-known patterns for either code or architecture, and using names that reveal the pattern (e.g. Facade, Proxy, Factory, Adapter) can reveal much to the pattern-literate developer (IMHO all developers should learn by heart the top 20 design patterns). Combined with a little Javadoc and possibly a few diagrams, the code now communicates itself. Sometimes there's no way around it -- some code is complex because the problem it's trying to solve is complex and does not yield to a simple implementation. In those cases, a few lines of JavaDoc will clear things up for the reader. Lastly, by its very nature, coding is at the "trees" level of organization and cannot easily reveal the "forest" level of architectural design. Then you'll need some UML diagrams and possibly some extended text. Lastly lastly, I hate asking myself "Why did they do it that way???" The reader can be helped much when the author reveals the rationale for designing or coding a certain way, especially if it deviates from well-known patterns. Thanks for triggering my thoughts, Adam. I'll add this to the documentation page. Keith Pierce On Tue, Feb 19, 2008 at 10:44 PM, Adam Monsen <[EMAIL PROTECTED]> wrote: > Recent conversations with communication superstars Kevin Shea and Ed > Cable inspired me to initiate some goals for Mifos documentation. I > didn't find any existing ones, so I jotted down my notes here: > > http://mifos.org/developers/wiki/DocumentationGoals > > Cheers? Jeers? > > -- > Adam Monsen > > > ------------------------------------------------------------------------- > This SF.net email is sponsored by: Microsoft > Defy all challenges. Microsoft(R) Visual Studio 2008. > http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ >
------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
