Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Attribution

  • 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 notbe 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 Eclipseto generate consistently formatted code
    • Simply use

      control-shift-f

      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

    control-shift-o

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

Deprecation

  • 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

Security

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

Do not comment out code

Do not leave commented out code in the source files. Just remove it. There are some exceptions of course, such as: "When I'm pretty sure it needs re-enabled at some point, and to make sure I don't forget why that is, I leave a clear TODO comment, e.g. "TODO this needs re-enabled when TRUNK-XXXX is fixed". Most IDEs are good at parsing out all TODO statements." Rowan Seymour

 

 

  • No labels