I would also like to add my 2cents. I agree with all the points below,
especially intention-revealing-code. However for parts that implement
business rules (that are not obvious), adding a few lines to explain things
would make it so much easier. Granted I have yet to understand a lot more in
the codebase but below are two examples that stumped me..
1. In LoanBO.java ->applyRounding()
the business rule is only applied if principal is not zero in any
installment.. nowhere could i find the information as to why this is so?
including the functional specification
2. another example (where someone else was already confused before me ;-)
org.mifos.application.accounts.savings.util.helpers ->savingHelper class
public class SavingsHelper {
private Calendar cal;
// TODO: pick from configuration
/** I assume the hardcoding of 1 Jan 2006 is trying to say
that the default fiscal year is January 1 to December 31.
Do we use the year?
What does this control, versus
[EMAIL PROTECTED] SavingsConstants#POSTING_DAY}? */
public Date getFiscalStartDate() {
try {
SimpleDateFormat format = new SimpleDateFormat("dd/MM/yyyy");
return format.parse("01/01/2006");
} catch (ParseException pe) {
throw new RuntimeException(pe);
}
}
-Soham
_____
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of Van
Mittal-Henkle
Sent: Wednesday, February 20, 2008 11:33 PM
To: Developer
Subject: Re: [Mifos-developer] Mifos documentation goals
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#javastand
ards
--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/
