Hi Van,
Thanks for your reply. By adding javadoc comments at this moment I dont
mean to sit and add the javadoc now. I meant that at this stage developers
to write comments as and when you see some code without comments when
fixing a bug.
I know that current code will certainly be replaced with better designed
code but any comments on current code will help a lot when supporting and
maintaining the release made on this codebase.
Also I am not only saying to add javadoc but also comments on some logical
code.like :
/* What is it doing and how*/
if(*some logic*) {
// more code
}
About the conditional logs, I somehow dont agree with you that it will
decrease code readability. When traversing a code most of us do ignore
the log statement. so
if(log.isDebugEnabled) {
log.debug("some exception trace");
}
will be similar for developer as :
log.debug("some exception trace");
But will definately improve runtime performance by avoiding string
creation. And this I am saying when the system is under heavy load like
when a report is being generated or a batch job is being executed.
Thanks and regards
*ravi
"Van Mittal-Henkle" <[EMAIL PROTECTED]>
Sent by: [EMAIL PROTECTED]
20/02/2008 18:02
Please respond to
Developer <[email protected]>
To
"Developer" <[email protected]>
cc
Subject
Re: [Mifos-developer] *MifOS coding review*
Hi Ravi,
I'm glad to see that you are reaching some of the same conclusions that
rest of us currently working on Mifos have reached in regards to how we
can improve the code base :-)
The project definitely is lacking when it comes to documentation, so
including javadocs where it helps to clarify the code and usage is a good
thing. As Adam and Keith have mentioned in subsequent postings, we should
also be on the lookout for cases where refactoring the code to make it
more descriptive would be a better choice than generating javadocs.
In general fine grained javadocs are most useful when there is a stable
enough code base that docs will not have to be repeatedly rewritten or
discarded as refactoring and redesign occurs. So my one caution would be
against spending too much time at this stage generating javadocs for code
that will likely change or go away. Once we've had time to get our design
the way we want it, then we'll be in a better position to put together
some real javadocs.
With respect to logging, I would suggest that logging with a conditional
statement only be used when there is a know performance issue with
evaluating the parameters being passed. In these cases it may first be
worth asking if the expesive parameters are necessary. Otherwise using
conditionals as a matter of course decreases code readability.
--Van
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of Ravi
Kutaphale
Sent: Monday, February 18, 2008 6:40 AM
To: Developer
Cc: Massimiliano Parlione
Subject: [Mifos-developer] *MifOS coding review*
Hi All,
Recently I started to go through the MifOS code to fix a bug assigned to
me.
Looking at the code I would like to make some comments and want everyone
to *seriously* follow the general coding standards.
I have noticed :
i) Most code does not have javadoc comments, it will be helpfull for
others to understand the code when they work on it.
Specially for opensource projects there should be 2 lines of comments
for every logical statement. Dont just think like a
coder when writing code, think as a analyst, this will help you to
write more comments.
ii) Proper naming for java classes. I saw some class names are too long
while others are too short with lots of shortnames.
Also the class name should be meaningfull and the name should reflect
what it does.
Ex. There is a class called AccountActionDateEntity. Now this class
holds the information about the actions taken on an account
so the name AccountActionEntity would be better option than
AccountAction"Date"Entity.
iii) Bullet (ii) also applies to method names.
iv) Logging : Some classes log too little and other too much. Its upto you
as to what logs you want to view when you want to fix a bug/issue.
Also the logging level needs to be checked before writing a message
to a log.
Ex : When when logging something at debug level.
if(log.isDebugEnabled()) {
log.debug(".......................", e);
}
This practice will help in not using resources used to generate the
log statements which will end up not being logged.
The MifosLogger does not provide the interface to check if the log
levels are enabled or not, maybe we will need to do so.
I would suggest that when you are fixing some bug and pass thru some
complicated code and you understand the logic of it then just add the
comments on it if they dont exist.
Thanks and regards
*ravi
-------------------------------------------------------------------------
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/
