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.
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.
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
- 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 http://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 some place 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 smart completion in your IDE and other ways of reducing typing).
- Serialization is for servlet sessions and need not work over program upgrades.
- 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.
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".
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).
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/
- The only script required on JSP/FTL is the import directive for javascirpt files.
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.
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.