Coding Guidelines for Bahmni

Guidelines

This document lays down coding guidelines, best practices and gotchas for developers to keep in mind.


General Guidelines for Code

Java/Python Codebases

  1. Coding styles are important but not overbearing.
  2. Code is neat, readable. 
  3. Follow SOLID principles
  4. DRYdivide code and logic into small reusable units - reuse. Less code is good
  5. ROT code? - surely someone has come up against it? Use a known library if you can’t find already plugged in. At the same time, you don't want to a introduce a library dependency for relatively simple and singular purpose. (e.g. introduce commons-lang library for a function that checks a string for being null or empty)
  6. Unused code - Don’t carry dead code, including commented off code is not useful and just baggage and often confusing. We use git anyways and all editors show a pretty good diff between versions!
  7. Create a "TECH DEBT" card, if you notice too much of duplicate code already in existing codebase, but you don't have the time to do that yourself.   
  8. Loops have definite set length and correct termination conditions.
  9. Use Java paradigms like 
    • Use of closeable in try-with-resources
    • Using streams
    • Loops like “names.forEach”
    • Lambda expressions
  10. The code must not break any existing feature during upgrades
    1. Data migrations if needed must be done so as to persist and keep working with existing transactional data.
    2. Configuration if introduced must have the previous behavior as the default, with options of extending/changing the behavior. Meaning, using existing configuration with new code does not require updates by any implementation. Configurations are documented and reflected with the release version indicated.
    3. Feature behaves, as much as possible, like before and is easy to pick up and preferably does not require retraining of end users.
  11. Is the code performant? Has it been tested with enough representative data? (Ask the contributor to share what they've done, or test it yourself if you have concerns.)

Bahmni Java libraries and modules for OpenMRS

Unit/Integreation Tests

Avoid repetition of similar task in each and every test, since the Before annotation setup method runs before each and ever test, and if you need something run before class then use the BeforeClass annotation. 

Try and move all Data setup XMLs to bahmni-test-commons, avoid duplication of data setup XMLs at all costs. Also try to move all builders, or any code which might be relevant for other unit tests to the bahmni-test-commons module. 


Spring Context/Beans

Take care of spring wiring, don't do a blind huge component scan on all the packages where some of them might not even include components, this increases the applications startup time. 

Avoid redundancy of Hibernate mapping files, there is no need for that. If a Maven Module is a dependency then the application Context XML will be included in the parent module as well, so the mapping will be inherited. 



Bahmni UI Coding Guidelines


  • The mobile browsers (iPad and Android) do not support parsing ISO dates. Avoid using new Date(dateString) for parsing dates. Use DateUtil.parse() instead (which uses moment.js).
  • In order to disable a "Submit" button, rely on checking the form's validity, rather than checking if a validation method passes. Make validation methods mark the input control as invalid, which indirectly will make form as invalid. That way the Submit button will get enabled only if the form is valid, which means all input controls on the form is valid. This will keep your submit method enabled/disable logic straightforward.
  • Avoid using self-closing html tags for span, divs. The <span/> will be converted to <span> by grunt html validator and minifiers. The "dist" doesn't work as expected. Use <span></span> instead of <span/>. See http://stackoverflow.com/questions/3558119/are-self-closing-tags-valid-in-html5

  • More angular guidelines related to performance boost is here.



References

There are enough guidelines available on internet to help you. 

Java

  1. https://www.javacodegeeks.com/2015/06/java-programming-tips-best-practices-beginners.html
  2. https://medium.com/@rhamedy/a-short-summary-of-java-coding-best-practices-31283d0167d3
  3. Oracle technet (now archived) - https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-137265.html
  4. https://docs.oracle.com/cd/A97688_16/generic.903/bp/java.htm


React 

  1. https://reactjs.org/docs/thinking-in-react.html


Angular

  1. Angular Guidelines related to performance


Python 

  1. https://airbrake.io/blog/python/python-best-practices