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