Coding Standards

Owned by Former user (Deleted)
Last updated: Mar 07, 2011 by Michael VorburgerVersion comment

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

  1. Mifos is used in branch offices.
  2. Both rural and urban branch offices are common.
  3. Connection speeds range from 56K dial-up to a max of 512 KBPS.
  4. Power outages, surges and networks outages are common in many areas.
  5. Some MFI's move from a ledger system to Mifos. They manage 1000's of clients on paper.
  6. For many end users, Mifos might be the first professional electronic system they have used.
  7. 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.
  8. Branches usually only have one PC.
  9. We encourage UPS, but sometimes it's not possible.
  10. Branches are not air conditioned.
  11. Loan officers must reconcile their collections, enter data and complete reporting on the same day for hundreds of clients on a single PC.
  12. MFI's do not necessarily have a full IT/MIS staff.
  13. Storage, RAM, CPU--all of these things are expensive.

Source code

With few exceptions, all plain text source code should be formatted as follows:

  • indent with 4 spaces per indent level, no tabs
  • wrap lines at 120 characters
  • end files with your operating system's end-of-line character (in Eclipse, this looks like an extra empty line at the end of a file)

In the "classical" workspace this is stored in the mifos-gazelle Project Properties Java Code Style > Formatter and directly available without further manual configuration.

In the Workspace 2.0 this configuration must be loaded into each new workspace once, see Workspace 2.0 Source Formatting Set-Up.

Developer Setup also has further (non-Workspace 2.0 related) Eclipse Workspace Preferences which must be set.

Java Standards

We mostly follow the standard Java conventions.

"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

  1. Write programs for people first, computers second!
  2. Remember that the end users can be on dial-up connections of 56K and less. See #End User Conditions for more information.
  3. Break up large methods and classes
  4. Avoid "clever" method overloading
  5. 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).
  6. Avoid "mysterious" numbers - all values should be related to the domain context (for example, by making appropriate constants)
  7. Write test cases before writing the code they test (see for example http://testdriven.com for how to work this way)
  8. 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.
  9. 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 some place harder to find.
  10. 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 smart completion in your IDE and other ways of reducing typing).
  11. Serialization is for servlet sessions and need not work over program upgrades.
  12. Generally avoid overriding equals, but see EqualsHashCodeIssues 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 a mailing list 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 a mailing list 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 "TODO".

Write javascript to the W3C DOM; it is neither necessary nor 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).

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

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).

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).

Markups

Please do not use html <table> tag for page layout. Use <table> only to display 2 dimensional/tabular data. Avoid nested <table> Use <fieldset>, <ol>, <ul>, <li>, <div> with CSS to define page layouts.

See ftls following these patterns in "questionnaire/src/main/resources/org/mifos/platform/questionnaire/ui/views/"

Also note that, the new freemarker views are being written to render XHTML 4 transitional markups. So, please take care of validating your markup compliance. You can do so using http://validator.w3.org/

Javascript

Consider using/finding a jquery plugin before writing custom js. Javascript libraries (jquery and its plugins, jstree, datejs) are moved to "userInterface/src/main/webapp/pages/js/" Please use un-obtrusive Javascript.

  • Do not write Javascript within JSP/FTL files, even in the form of event handling method calls.
  • The only script required on JSP/FTL is the import directive for javascirpt files.
  • Jquery makes it easy to write unobtrusive Javascript. See examples in "questionnaire/src/main/webapp/pages/questionnaire/js/"

Templates and layouts in Freemarker

Use FTL page layouts instead of adding header, footer and left pane in every page. Add new layouts in "userInterface/src/main/resources/org/mifos/ui/freemarker/core/layout.ftl" Layout usage can be seen in "questionnaire/src/main/resources/org/mifos/platform/questionnaire/ui/views/viewQuestionDetail.ftl" Main contents in FTLs should be enclosed in "content_panel" div.

Database

Write portable SQL. Although production use of other databases (postgres, for example) is not a high priority, generally portable SQL is also simpler and easier to understand and maintain than database-specific tricks.

Please make sure you are familiar with the end user conditions.

See also