Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0
Table of Contents


  • Attribution is to be done within commit comments.
  • When a committer is applying a patch, the author(s) of the patch should be attributed within the commit comment according to the the comment conventions.
  • Attribution (either author or contributing authors) should not be placed into source code. When encountered, such attribution should be removed by (or with permission from) the original author(s). Contributions that require attribution (i.e., author(s) demanding attribution within the code contributions) will be graciously refused or removed from the repository.

    (NOTE: this attribution-free coding policy took effect after version 1.1, so you may see some attribution in the existing code; we are gradually removing attribution from our code base)

Code Style

  • We use the automatic formatting feature of Eclipse to generate consistently formatted code
    • Simply use
      Code Block
      to format a file
    • OpenMRS formatting file for Eclipse: OpenMRSFormatter.xml
      • Install at Window -> Preferences -> Java -> Code Style -> Formatter
    • OpenMRS code template file for Eclipse: OpenMRSCodeTemplate.xml
      • Install at Window -> Preferences -> Java -> Code Style -> Code Templates
  • Use
    Code Block
    for finding/formatting/organizing imports - Very useful!

Exception Handling Conventions

Create an intuitive hierarchy of exceptions within the package they belong, only creating new Exception classes for when the need to branch on different types of exception within code/webapp are needed (add as needed instead of making extra classes "just in case" for every possible variation).

For example:


org.openmrs.api.PatientIdentifierException extends APIException
org.openmrs.api.MissingPatientIdentifierException extends PatientIdentifierException

and later add:


org.openmrs.api.DuplicatePatientIdentifierException extends PatientIdentiferException

when we realize the webapp needs to distinguish duplicates from invalid identifier exceptions.

Patching Third Party Libraries

Use of StringUtils

  • Do not do this: "if (s == null || s.equals("")) ...". Instead do "if (StringUtils.isNotEmpty(s) ..."
  • We have both the apache commons StringUtils and springframework StringUtils library. If possible, use the apache commons StringUtils method. However, if the spring StringUtils is already imported, use that one.


  • We deprecate public methods instead of changing/deleting them in order to preserve backwards compatibility. We will delete all deprecated methods when we make a new version (eg from 1.x to 2.0)
  • Use both the @deprecated annotation and the @Deprecated javadoc comment
  • The @Deprecated javadoc annotation should point to the new method that is replacing the current one
  • DAO methods do not have to go through a deprecation cycle. They can be changed/deleted outright

Document Return Value of Methods

  • Specify the return value of every method. Return values that should be documented are: null values, empty collections (whether an empty sets or empty list is always returned, etc)
  • Test this return value assumption and annotate them with @should


Avoiding XSS scripting

  • StringEscapeUtils.escapeJavaScript() and StringEscapeUtils.escapeHtml() to escape any user-generated data in pages.
    • StringEscapeUtils is an Apache class and its java doc can be found here
  • In the reference application (with the UI framework), use ui.escapeJs(), ui.escapeHtml(), and ui.escapeAttribute()