Thanks for the good documentation ideas, Adam and the thoughtful discussion about this, Keith. The list of documentation goals is a good starting place. I also agree wholeheartedly with Keith's comments below. In particular the idea that the mark of well written code is that for the most part it is self documenting (ie. INTENTION-REVEALING-CODE). As, is pointed out, there are still cases when additional documentation is useful, but when we find the need to explain our code, it is often useful to first look at the code and see if it can be refactored to make it's intention clear from the code itself. Hopefully as we add new code to the project we can all strive to write code that is clear on its own and as we work to understand existing code we can refactor it where doing so whill make that code easier to understand too. As some of these ideas are written down, we may want to link them to our brief existing reference to code and documentation which is on the following wiki: http://mifos.org/developers/technical-orientation/coding-standards#javas tandards --Van
________________________________ From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Keith Pierce Sent: Wednesday, February 20, 2008 6:59 AM To: Developer Subject: Re: [Mifos-developer] Mifos documentation goals 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/
