Hi Keith,
can you highlight piece of code in Mifos that are good examples of
INTENTION-REVEALING-CODE?
It will be easy for us to follow these good examples.
Best
"Keith Pierce"
<[EMAIL PROTECTED]
m> To
Sent by: Developer
mifos-developer-b <[EMAIL PROTECTED]
[EMAIL PROTECTED] net>
ceforge.net cc
Subject
02/20/2008 02:59 Re: [Mifos-developer] Mifos
PM documentation goals
Please respond to
Developer
<mifos-developer@
lists.sourceforge
.net>
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/
-------------------------------------------------------------------------
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/
