Product
 
Home > Developers > Technical Orientation > Coding Standards
Document Actions

Coding Standards

End User Conditions

The user base for Mifos is microfinance institutions, and you need to be mindful of the conditions when designing, creating, or fixing Mifos.  Read more on How Mifos Is Used

  • Mifos is used in branch offices.
  • Both rural and urban branch offices are common.
  • Connection speeds range from 56K dial-up to a max of 512 KBPS.
  • Power outages, surges and networks outages are common in many areas.
  • Some MFI's move from a ledger system to Mifos. They manage 1000's of clients on paper.
  • For many end users, Mifos might be the first professional electronic system they have used.
  • Banks in some countries/regions may refuse deposits after a certain time, so data entry flow is critical when you must enter data for several hundred clients a day.
  • Branches usually only have one PC.
  • We encourage UPS, but sometimes it's not possible.
  • Branches are not air conditioned.
  • Loan officers must reconcile their collections, enter data and complete reporting on the same day for hundreds of clients on a single PC.
  • MFI's do not necessarily have a full IT/MIS staff.
  • Storage, RAM, CPU--all of these things are expensive.

Java Standards

 

We mostly follow the standard Java conventions found at http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

"If builders built buildings the way programmers wrote programs, then the first woodpecker that came along would destroy civilization" (Gerald Weinberg)

We subscribe to the notions that code should be expressive, simple to read, non-repetitive, and consistent

  • Write programs for people first, computers second!
  • Remember that the end users can be on dial-up connections of 56K and less. See End User Conditions for more information.
  • Break up large methods and classes
  • Avoid "clever" method overloading
  • Prefer using named variables, not temporaries, as constructor parameters (for example, MyObject(String streetAddress, String postalCode) - rather than names like sa, tStreetAddress, pStreetAddress, sAddress, etc).
  • Avoid "mysterious" numbers - all values should be related to the domain context (for example, by making appropriate constants)
  • Write test cases before writing the code they test (see for example testdriven.com for how to work this way)
  • When setting up fields of an object, prefer to pass values into a constructor rather than have setter methods. Make the fields final where appropriate.
  • When documenting the code, the order of preference is (1) the code itself is clear, (2) comments near the relevant lines of code (but not ones that merely re-state what the code says), (3) comments in a more global place, like the top of a method, class, or package, (4) wiki pages, (5) other documents checked into subversion, and least preferred is (6) other documents kept in email folders or someplace harder to find.
  • Name variables clearly. Avoid acronyms where possible. For example write "tokenizer" rather than "st" for a StringTokenizer. You spend more time reading code than writing it, so don't be afraid of some extra keystrokes (and learn about control-space in Eclipse and other ways of reducing typing).
  • Serialization is for servlet sessions and need not work over program upgrades.
  • Generally avoid overriding equals, but see Equals and Hashcode Issues for details.


To the extent that the existing code doesn't do these things, it can be considered a to-do item. Please do ask on the Listserv if you unsure about anything; setting coding standards is an ongoing discussion among developers.

HTML Standards

First, the disclaimer. As with other Coding Standards, what is on this page is subject to change based on what browsers people are actually testing with, discussion among developers, etc. So feel free to ask on the Listserv if you are working on some code and have questions. Also note that the current mifos code obeys some of these rules more than others. So to the extent that it doesn't, it can be considered a to-do task.

Write javascript to the W3C DOM; it is neither necessary or desirable to cater to older javascript DOMs (roughly, W3C DOM means IE5, Mozilla, or newer, but not Netscape 4, IE4 or older).

Don't use javascript when there is a perfectly good way of doing something in HTML or CSS. Usually this kind of javascript gets subtle details wrong (for example, whether the user can see the destination of a link by hovering over it). Input should not be validated until form submission.

Assume a relatively capable CSS implementation (again, corresponding to IE5 or Mozilla). I think this means CSS1 and parts of CSS2, roughly.

Don't layout with non-breaking-spaces all over the place, transparent gifs, or tons of tables. Those are obsolete practices given the CSS criterion above.

However, don't be afraid to use some tables for layout. There are things that CSS does not yet do well (for example, dividing the horizontal space between a sidebar and a main pane, keeping in mind that the window might be resized by the user).

All HTML should be well-formed XML. If you render via XmlBuilder, this is basically provided for you. (Quick summary of what "well-formed" means: start tags like <p> are always balanced by end tags like </p>; single tags like <br /> have the trailing slash - see XML spec for details).

Making our pages valid XHTML 1.0 is a good idea too, but might be farther down the road.

It is desirable to work with textual browsers such as lynx/links/w3m, cell phone browsers, browsers without javascript enabled, etc. (However, whether this happens depends largely on whether people test with those devices and send in patches. Don't get too worried about what might happen on some browser you don't have access to. On the flip side, don't go through contortions to make things Just Right on one particular browser. Hackery will probably just break in a future release of that browser, anyway. Instead, focus on straightforward HTML).

 

See also

 

 

last modified 2008-01-29 10:58
Grameen logo