{"type":"doc","content":[{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"OpenMRS tries to follow a common coding style in order to make our code base robust: more readable and more reliable (if the same code is created by three different developers, it should look and read very similar). Our style conventions are designed to promote consistency and good coding practices, while reducing common errors. If you feel that our coding styles could be improved (by changing, adding, or removing something), please bring your comments to the ","type":"text"},{"text":"Developers Mailing List","type":"text","marks":[{"type":"link","attrs":{"href":"http://go.openmrs.org/dev"}}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"We use a combination of tools (checkstyle, PMD, FindBugs, ...) to write down our coding conventions in a set of rules. These rules are picked up by services (provided by our own infrastructure like SonarQube or cloud providers like codacy) so that any addition of new code (via a commit or pull request on Github) is checked for violations of these rules. Having the rules in simple config files together with the source code enable any developer to run the same checks locally.","type":"text"}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"2f3dbd6c-e704-4c9c-a509-4360b8814ec0"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Tools","type":"text"}]},{"type":"paragraph","content":[{"text":"The following tools are used to ease code review, help new developers get used to our coding style and maintain code quality.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Checkstyle","type":"text"}]},{"type":"paragraph","content":[{"text":"We use ","type":"text"},{"text":"checkstyle","type":"text","marks":[{"type":"link","attrs":{"href":"http://checkstyle.sourceforge.net"}}]},{"text":" for static code analysis. checkstyle defines rules","type":"text"},{"text":" http://checkstyle.sourceforge.net/checks.html","type":"text","marks":[{"type":"link","attrs":{"href":"http://checkstyle.sourceforge.net/checks.html"}}]},{"text":" which when violated in the code will result in errors or warnings. The checkstyle rules we want our code to adhere to are defined in the openmrs-core repostitory's ","type":"text"},{"text":"checkstyle.xml","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-core/blob/master/checkstyle.xml"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Manual Run","type":"text"}]},{"type":"paragraph","content":[{"text":"You can run checkstyle locally using the ","type":"text"},{"text":"maven checkstyle plugin","type":"text","marks":[{"type":"link","attrs":{"href":"https://maven.apache.org/plugins/maven-checkstyle-plugin/index.html"}}]},{"text":" with the following command","type":"text"}]},{"type":"codeBlock","content":[{"text":"mvn clean compile jxr:aggregate checkstyle:checkstyle-aggregate","type":"text"}]},{"type":"paragraph","content":[{"text":"This will generate an html report at","type":"text"}]},{"type":"paragraph","content":[{"text":"target/site/checkstyle-aggregate.html","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"(the path is relative to the root of the openmrs-core repository)","type":"text"}]},{"type":"paragraph","content":[{"text":"The report will show you all the violations for each java class with their severity, the name of the rule and the location (the jxr portion in the above command enables you to navigate to the location of the violation in the java class). If you want to know more about a specific rule go to ","type":"text"},{"text":"http://checkstyle.sourceforge.net/checks.html","type":"text","marks":[{"type":"link","attrs":{"href":"http://checkstyle.sourceforge.net/checks.html"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"PMD","type":"text"}]},{"type":"paragraph","content":[{"text":"PMD","type":"text","marks":[{"type":"link","attrs":{"href":"https://pmd.github.io"}}]},{"text":" is used to check for issues like unused, unnecessary or error prone code. The PMD rules we want our code to adhere to are defined in the openmrs-core repostitory's ","type":"text"},{"text":"ruleset.xml","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-core/blob/master/ruleset.xml"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Manual Run","type":"text"}]},{"type":"paragraph","content":[{"text":"Install PMD locally and try","type":"text"}]},{"type":"codeBlock","content":[{"text":"./pmd-bin-5.5.4/bin/run.sh pmd -d openmrs/openmrs-core/api/src/main/java -f text -R openmrs/openmrs-core/ruleset.xml -version 1.8 -language java","type":"text"}]},{"type":"paragraph","content":[{"text":"Adjust the version and location of the PMD you installed and refer to the ","type":"text"},{"text":"PDM documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://pmd.github.io/pmd-5.3.3/usage/running.html"}}]},{"text":" to see the available command line options.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"findbugs"},"legacyAnchorId":{"value":"JavaConventions-findbugs"}},"macroMetadata":{"macroId":{"value":"19074330-8211-4156-806b-fb8c88e8ec3b"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"FindBugs","type":"text"}]},{"type":"paragraph","content":[{"text":"FindBugs","type":"text","marks":[{"type":"link","attrs":{"href":"http://findbugs.sourceforge.net/"}}]},{"text":" is another tool we use to check the code for issues. The FindBugs rules we want our code to adhere to are defined in the openmrs-core repository's ","type":"text"},{"text":"findbugs-include.xml","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-core/blob/master/findbugs-include.xml"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Manual Run","type":"text"}]},{"type":"paragraph","content":[{"text":"At the moment you cannot check the code against the FindBugs rules locally using maven as with checkstyle. ","type":"text"},{"text":"We are working","type":"text","marks":[{"type":"link","attrs":{"href":"https://issues.openmrs.org/browse/TRUNK-5083"}}]},{"text":" on it ","type":"text"},{"type":"emoji","attrs":{"id":"1f642","text":"🙂","shortName":":slight_smile:"}}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Automation","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Codacy & Github Integration","type":"text"}]},{"type":"paragraph","content":[{"text":"We have set up integration with ","type":"text"},{"text":"codacy","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.codacy.com/app/openmrs/openmrs-core/dashboard"}}]},{"text":" so that our rules will be checked on every pull request. Whenever you make a pull request your code will be commented by codacy and if its clean the check will pass and if not show you what parts of your code violated which rules. You can see the current status of the openmrs-core at ","type":"text"},{"text":"https://www.codacy.com/app/openmrs/openmrs-core/dashboard","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.codacy.com/app/openmrs/openmrs-core/dashboard"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"SonarQube","type":"text"}]},{"type":"paragraph","content":[{"text":"SonarQube checks the openmrs-core code once a day. You can find the issues it found ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://ci.openmrs.org/sonar/dashboard/index/org.openmrs:openmrs"}}]}]},{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"FindBugs","type":"text","marks":[{"type":"link","attrs":{"href":"#JavaConventions-findbugs"}}]},{"text":" to see where the rules come from.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Limitations & Work In Progress","type":"text"}]},{"type":"paragraph","content":[{"text":"We aim to bring all our rules (FindBugs, ESLint) into the openmrs-core repository and to let codacy use both set of rules to check the code. Codacy is currently configured to read our checkstyle and PMD rules from the repository to check Java code that goes into it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Other languages such as javascript, ruby, ... might be checked as well but we do not yet have formalized these rules into config files like ESLint or JSHint. If you want to do that go ahead!","type":"text"}]},{"type":"paragraph","content":[{"text":"FindBugs rules will not be checked by codacy since that is a feature only available to enterprise users. If you know another cloud provider that satisfies our needs and supports FindBugs please tell us!","type":"text"}]},{"type":"paragraph","content":[{"text":"The topic is discussed here:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"formalize coding rules","type":"text","marks":[{"type":"link","attrs":{"href":"https://talk.openmrs.org/t/formalize-openmrs-core-coding-rules-and-style/10307/2"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"codacy integration","type":"text","marks":[{"type":"link","attrs":{"href":"https://talk.openmrs.org/t/codacy-in-openmrs-core-prs/5708/19"}}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"How-To Write Code According to the Conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"Make sure you have followed the ","type":"text"},{"text":"How-To Setup And Use Your IDE","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25506949"}}]},{"text":" so that your code changes will automatically be formatted according to the OpenMRS style.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Unit Tests","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add the OpenMRS code templates to your IDE (","type":"text"},{"text":"Eclipse","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469726#DeveloperHow-ToSetupAndUseEclipse-ToSetupAndUseEclipse-add-templatesAddOpenMRSCodeTemplates"}}]},{"text":" or ","type":"text"},{"text":"IntelliJ","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469543#DeveloperHow-ToSetupAndUseIntelliJ-ToSetupAndUseIntelliJ-add-templatesAddOpenMRSCodeTemplates"}}]},{"text":") which will make it easy for you to insert tests according to our conventions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Read and follow ","type":"text"},{"text":"Unit Testing Conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25471351"}}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"The following conventions are applied to code in openmrs-core but we encourage module authors to adopt them as well.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"File template","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OpenMRS License Header","type":"text","marks":[{"type":"strong"}]},{"text":". All code should start with the OpenMRS license header which can be found ","type":"text"},{"text":"OpenMRS core repository","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-core/blob/master/license-header.txt"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"File Length","type":"text","marks":[{"type":"strong"}]},{"text":". Files should not exceed 2500 lines. If your class exceeds this length, consider refactoring your code to break it into more reasonably sized files. Overly large classes are harder to read.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One class per file","type":"text","marks":[{"type":"strong"}]},{"text":". Do not put more than one class in your .java file(s).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attribution","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Attribution is to be done ","type":"text"},{"text":"within commit comments","type":"text","marks":[{"type":"strong"}]},{"text":" according to the ","type":"text"},{"text":"the comment conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25520737#SubversionCodeofConduct-Applyingpatchestotrunkandotherbranches"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Attribution (either author or contributing authors) ","type":"text"},{"text":"should ","type":"text","marks":[{"type":"strong"}]},{"text":"not","type":"text","marks":[{"type":"em"},{"type":"strong"}]},{"text":" be placed into source code","type":"text","marks":[{"type":"strong"}]},{"text":". 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.","type":"text"}]}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"(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)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Code Style","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Include curly braces around ","type":"text"},{"text":"if","type":"text","marks":[{"type":"code"}]},{"text":" clauses, and loops even when there is only a single statement inside, that is, instead of this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"if (!someBooleanFlag)\n\t...perform something with a one liner;","type":"text"}]},{"type":"paragraph","content":[{"text":"Write this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"if (!someBooleanFlag){\n\t...perform something with a one liner;\n}","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For classes that extend BaseOpenmrsObject, do not override the ","type":"text"},{"text":"equals()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"hashcode()","type":"text","marks":[{"type":"code"}]},{"text":" methods ","type":"text"},{"text":"unless","type":"text","marks":[{"type":"strong"}]},{"text":" this is necessary for the semantics of the class. If you do override ","type":"text"},{"text":"equals()","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"hashcode()","type":"text","marks":[{"type":"code"}]},{"text":" , be sure that you override both of them.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid unnecessary else statements. normally you should be able to configure your IDE to catch this and warn you about it. That is instead of this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"public boolean doSomething(boolean shouldDoSomething){\n\tif (!shouldDoSomething){\n\t\treturn false;\n\t} else {\n\t\t//.... do something\n\t\treturn true;\n\t}\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Write this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"public boolean doSomething(boolean shouldDoSomething){\n\tif (!shouldDoSomething){\n\t\treturn false;\n\t}\n\n\t//.... do something\n\treturn true;\n}","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Favouring return types that refer to interfaces rather than concrete implementations where possible. This is especially true for objects from the Java Collections API. For example, favour returning ","type":"text"},{"text":"List","type":"text","marks":[{"type":"code"}]},{"text":" over ","type":"text"},{"text":"LinkedList","type":"text","marks":[{"type":"code"}]},{"text":" . This way the implementation can be changed without affecting code that relies on the return type.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When writing services, the ","type":"text"},{"text":"@Transactional","type":"text","marks":[{"type":"code"}]},{"text":" annotation should be added to the implementing class at the class level and not to the interface. All methods that don't write to the database, e.g getXXX methods, should have their own ","type":"text"},{"text":"@Transactional","type":"text","marks":[{"type":"code"}]},{"text":" annotation with the ","type":"text"},{"text":"readOnly","type":"text","marks":[{"type":"code"}]},{"text":" attribute set to true.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java 8 lambdas should only be used for short, easily understood blocks of code and should not be wrapped in curly braces unless absolutely necessary. That is, instead of this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"myList.stream().map(item -> {\n\treturn item.getCost() * 1.05;\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"Write this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"myList.stream().map(item -> item.getCost() * 1.05);","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Where possible, use method references instead of lambdas. That is, instead of this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"myList.stream().map(item -> item.toString());","type":"text"}]},{"type":"paragraph","content":[{"text":"Write this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"myList.stream().map(Object::toString);","type":"text"}]},{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Imports","type":"text"}]},{"type":"paragraph","content":[{"text":"Make sure you have followed the ","type":"text"},{"text":"How-To Setup And Use Your IDE","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25506949"}}]},{"text":" which will prevent you from running into the following issues.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remove unused imports","type":"text"}]},{"type":"paragraph","content":[{"text":"Imports that are not used should be removed, remember that you introduce dependencies that are not needed!","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Do not use wildcard imports","type":"text"}]},{"type":"paragraph","content":[{"text":"If you are importing multiple classes from a package, list them all individually, like in the following code block, since this makes it clear exactly what imported classes are in use in any file:","type":"text"}]},{"type":"codeBlock","content":[{"text":"import java.util.ArrayList;\nimport java.util.List;\nimport java.util.Random;","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not do the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"import java.util.*;","type":"text"}]},{"type":"paragraph","content":[{"text":"Please check your IDE settings it is often the IDE which merges several imports into a wildcard import.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Naming Conventions","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Package names should be lowercase without punctuation, following Java specs.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Class and interface names should be capitalized (using CamelCase), begin with a letter, and contain only letters and numbers.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Method names should follow Java specs.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Parameter names should follow Java specs.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Class and instance variables should follow Java specs. Any constants should be written in uppercase letters.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Strings","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Concatenation","type":"text"}]},{"type":"paragraph","content":[{"text":"Since Java 6 String concatenation is implemented through the ","type":"text"},{"text":"StringBuilder","type":"text","marks":[{"type":"code"}]},{"text":" (or ","type":"text"},{"text":"StringBuffer","type":"text","marks":[{"type":"code"}]},{"text":") class and its ","type":"text"},{"text":"append","type":"text","marks":[{"type":"code"}]},{"text":" method (source: ","type":"text"},{"text":"String javadoc","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.oracle.com/javase/6/docs/api/java/lang/String.html 1"}}]},{"text":"). Commonly String concatenation is more readable than ","type":"text"},{"text":"StringBuilder","type":"text","marks":[{"type":"code"}]},{"text":" (or ","type":"text"},{"text":"StringBuffer","type":"text","marks":[{"type":"code"}]},{"text":"), because ","type":"text"},{"text":"takes up less space. ","type":"text"},{"type":"hardBreak"},{"text":"It is means that in most cases we should use","type":"text"},{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"String a = b + c + d;","type":"text"}]},{"type":"paragraph","content":[{"text":"instead of","type":"text"},{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"String a = new StringBuilder().append(b).append(c).append(d).toString();","type":"text"}]},{"type":"paragraph","content":[{"text":"For concatenation when logging","type":"text","marks":[{"type":"strong"}]},{"text":", see ","type":"text"},{"text":"How To Log","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/Java+Conventions#JavaConventions-HowToLog"}},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Use of StringUtils","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not do this: \"","type":"text"},{"text":"if (s == null || s.equals(\"\")) ...","type":"text","marks":[{"type":"code"}]},{"text":"\". Instead do \"","type":"text"},{"text":"if (StringUtils.isNotEmpty(s) ...","type":"text","marks":[{"type":"code"}]},{"text":"\"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Do not comment out code","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not leave commented out code in the source files. Just remove it. Others will think this has been left there for a purpose and thus will probably not dare to delete it which will leave this commented out code hanging around forever. 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.\" ","type":"text"},{"type":"mention","attrs":{"id":"712020:1317414b-83b5-4acb-95f8-6bebce5e53c4","text":"@Rowan Seymour"}}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"logging"},"legacyAnchorId":{"value":"JavaConventions-logging"}},"macroMetadata":{"macroId":{"value":"47003a7e-36c4-4fc3-a206-17a7d92b75dd"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Logging","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"OpenMRS uses the logging facade ","type":"text"},{"text":"https://www.slf4j.org/","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.slf4j.org/"}}]},{"text":" which in turn delegates to the log4j as the logging implementation. If you want some background info on these libraries and their relation to Apache commons-logging and spring read this","type":"text"},{"text":" http://docs.spring.io/spring/docs/4.1.4.RELEASE/spring-framework-reference/htmlsingle/#overview-not-using-commons-logging","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.spring.io/spring/docs/4.1.4.RELEASE/spring-framework-reference/htmlsingle/#overview-not-using-commons-logging"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How To Log","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to log you should rely on the slf4j. The following shows a typical usage borrowed from their ","type":"text"},{"text":"API documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.slf4j.org/apidocs/index.html"}}]}]},{"type":"codeBlock","content":[{"text":" import org.slf4j.Logger;\n import org.slf4j.LoggerFactory;\n\n public class Wombat {\n\n private static final Logger log = LoggerFactory.getLogger(Wombat.class);\n\n Integer t;\n Integer oldT;\n\n public void setTemperature(Integer temperature) {\n oldT = t;\n t = temperature;\n log.debug(\"Temperature set to {}. Old temperature was {}.\", t, oldT);\n if(temperature.intValue() > 50) {\n log.info(\"Temperature has risen above 50 degrees.\");\n }\n }\n } ","type":"text"}]},{"type":"paragraph","content":[{"text":"SLF4J 1.6.x is not supported more than two String arguments. In this case you can use","type":"text"}]},{"type":"codeBlock","content":[{"text":"log.trace(\"Time taken to store {} objects of size {} is {} msecs\", new Object[] { count, size, time });","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How To (Not) Log","type":"text"}]},{"type":"paragraph","content":[{"text":"You might need to construct a message for logging and want to prevent this construction from happening if the debug log level is not enabled. You could then come up with a pattern like this","type":"text"}]},{"type":"codeBlock","content":[{"text":"if(log.isDebugEnabled()) {\n log.debug(\"Entry number: \" + i + \" is \" + String.valueOf(entry[i]));\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"which you should not use even if you see it in existing code (if you see this clean it up).","type":"text"}]},{"type":"paragraph","content":[{"text":"Instead you should use ","type":"text"},{"text":"parametrized messages","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"log.debug(\"The entry is {}.\", entry);","type":"text"}]},{"type":"paragraph","content":[{"text":"Why? Read ","type":"text"},{"text":"https://www.slf4j.org/faq.html#logging_performance","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.slf4j.org/faq.html#logging_performance"}}]},{"text":" for the answer.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Code Templates","type":"text"}]},{"type":"paragraph","content":[{"text":"Add the OpenMRS code templates to your IDE (","type":"text"},{"text":"Eclipse","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469726#DeveloperHow-ToSetupAndUseEclipse-ToSetupAndUseEclipse-add-templatesAddOpenMRSCodeTemplates"}}]},{"text":" or ","type":"text"},{"text":"IntelliJ","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469543#DeveloperHow-ToSetupAndUseIntelliJ-ToSetupAndUseIntelliJ-add-templatesAddOpenMRSCodeTemplates"}}]},{"text":") which will save you typing and help you stick to the above conventions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"More Conventions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Do not print out","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"System.out.println()","type":"text","marks":[{"type":"strong"}]},{"text":". Do not use ","type":"text"},{"text":"System.out.","type":"text","marks":[{"type":"code"}]},{"text":"println()","type":"text","marks":[{"type":"em"}]},{"text":" in your code; instead ","type":"text"},{"text":"log","type":"text","marks":[{"type":"link","attrs":{"href":"#JavaConventions-logging"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ex.printStackTrace()","type":"text","marks":[{"type":"strong"}]},{"text":". Do not use ","type":"text"},{"text":"ex.","type":"text","marks":[{"type":"code"}]},{"text":"printStackTrace()","type":"text","marks":[{"type":"em"}]},{"text":" in your code; instead ","type":"text"},{"text":"log","type":"text","marks":[{"type":"link","attrs":{"href":"#JavaConventions-logging"}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Modifier order","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Modifiers should follow the order suggested by the ","type":"text"},{"text":"Java Language specification, sections 8.1.1, 8.3.1, 8.4.3","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html"}}]},{"text":" and ","type":"text"},{"text":" 9.4:","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html"}}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"public","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"protected","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"private","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"abstract","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"default","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"static","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"final","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"transient","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"volatile","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"synchronized","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"native","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"strictfp","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"We enforce this via Checkstyle ","type":"text"},{"text":"rule ModifierOrder","type":"text","marks":[{"type":"link","attrs":{"href":"http://checkstyle.sourceforge.net/config_modifier.html#ModifierOrder"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Others","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Long method signatures","type":"text","marks":[{"type":"strong"}]},{"text":". Method signatures should be kept under 400 characters in length.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Too many parameters","type":"text","marks":[{"type":"strong"}]},{"text":". Method signatures should have less than 20 parameters.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"new Boolean()","type":"text","marks":[{"type":"strong"}]},{"text":". You should not instantiate the ","type":"text"},{"text":"Boolean","type":"text","marks":[{"type":"code"}]},{"text":" class; rather, use ","type":"text"},{"text":"Boolean.TRUE","type":"text","marks":[{"type":"code"}]},{"text":" and/or ","type":"text"},{"text":"Boolean.FALSE","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"foo = bar = 0","type":"text","marks":[{"type":"strong"}]},{"text":". Avoid inline assignments; rather, break them into separate lines of code. Inline assignments can reduce code readability and may represent an error: equality (h1. ) accidentally entered as assignment (=).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Long lines","type":"text","marks":[{"type":"strong"}]},{"text":". Lines should not exceed 125 characters.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Switch default case","type":"text","marks":[{"type":"strong"}]},{"text":". All switch statements should have a ","type":"text"},{"text":"default","type":"text","marks":[{"type":"code"}]},{"text":" case if only to ","type":"text"},{"text":"assert false","type":"text","marks":[{"type":"code"}]},{"text":", since future coding changes may introduce unexpected cases.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Switch fall through","type":"text","marks":[{"type":"strong"}]},{"text":". All switch cases containing any code should end with a ","type":"text"},{"text":"break","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"return","type":"text","marks":[{"type":"code"}]},{"text":" statement to avoid accidentally falling through to the next case. In the rare case that you desire a fall through, the next case should be preceded with ","type":"text"},{"text":"/* fall through */","type":"text","marks":[{"type":"code"}]},{"text":" to indicate your intention.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Magic Numbers","type":"text","marks":[{"type":"strong"}]},{"text":". Literal numbers should only exist within constants, rather than being introduced directly in the code.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Literal Long Numbers","type":"text","marks":[{"type":"strong"}]},{"text":". Always use a capital L for long numbers, since a lowercase L (l) is easily confused with a one (1).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"equals() without hashCode()","type":"text","marks":[{"type":"strong"}]},{"text":". Classes that override ","type":"text"},{"text":"equals()","type":"text","marks":[{"type":"em"}]},{"text":" should also override ","type":"text"},{"text":"hashCode()","type":"text","marks":[{"type":"em"}]},{"text":"'.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Nested If Statements","type":"text","marks":[{"type":"strong"}]},{"text":". If statements should not be nested deeper than eight (8) levels.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Nested Try Statements","type":"text","marks":[{"type":"strong"}]},{"text":". Try statements should not be nested deeper than three (3) levels.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No clone()","type":"text","marks":[{"type":"strong"}]},{"text":". Classes should not override the ","type":"text"},{"text":"clone()","type":"text","marks":[{"type":"em"}]},{"text":" method.","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(expression false)","type":"text","marks":[{"type":"strong"}]},{"text":". Do not test equality with ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code"}]},{"text":"; rather, simplify the boolean expression by removing the comparison and, if necessary, adding a leading exclamation mark (!) if you are testing for ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code"}]},{"text":" expressions.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"if Statements. ","type":"text","marks":[{"type":"strong"}]},{"text":"If statements should always be enclosed in braces. Always write \"if (expr) {doSomething();}\", never write \"if (expr) doSomething();\"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Loop Braces","type":"text","marks":[{"type":"strong"}]},{"text":". There should be braces for the case of any loop even there is only one statement. Always write \"while (condition) {doSomething();}\", never write \"while (condition) doSomething();\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Documentation","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All classes and interfaces should, at a minimum, have a Javadoc comment at the class level","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Public methods should have a Javadoc comment","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code that performs any non-obvious task should be documented for clarification","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Test this return value assumption and annotate them with ","type":"text"},{"text":"@should","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469603"}}]},{"text":" as described by ","type":"text"},{"text":"Unit Tests","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469609"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Please note that the ","type":"text"},{"text":"commenting style from most textbooks is only a good practice when the comments are intended for a student learning to program. It is not intended for professional programmers.","type":"text"},{"text":" Take a look at these ","type":"text"},{"text":"best practices for commenting your code","type":"text","marks":[{"type":"link","attrs":{"href":"https://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/"}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Exception Handling","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"General","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"catch (Exception e) {}","type":"text","marks":[{"type":"strong"}]},{"text":". Do not catch ","type":"text"},{"text":"Exception","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"Throwable","type":"text","marks":[{"type":"code"}]},{"text":", or ","type":"text"},{"text":"RunTimeException","type":"text","marks":[{"type":"code"}]},{"text":"; rather, you should catch more specific exceptions. Catching these high level exceptions can mask errors.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"throw Throwable","type":"text","marks":[{"type":"strong"}]},{"text":". Do not throw ","type":"text"},{"text":"Throwable","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"Error","type":"text","marks":[{"type":"code"}]},{"text":", or ","type":"text"},{"text":"RuntimeException","type":"text","marks":[{"type":"code"}]},{"text":"; rather, you should throw more specific exceptions.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Creating Custom Exceptions","type":"text"}]},{"type":"paragraph","content":[{"text":"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).","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"panel","attrs":{"panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"org.openmrs.api.APIException","type":"text"},{"type":"hardBreak"},{"text":"org.openmrs.api.PatientIdentifierException extends APIException","type":"text"},{"type":"hardBreak"},{"text":"org.openmrs.api.MissingPatientIdentifierException extends PatientIdentifierException","type":"text"}]}]},{"type":"paragraph","content":[{"text":"and later add:","type":"text"}]},{"type":"panel","attrs":{"panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"org.openmrs.api.DuplicatePatientIdentifierException extends PatientIdentiferException","type":"text"}]}]},{"type":"paragraph","content":[{"text":"when we realize the webapp needs to distinguish duplicates from invalid identifier exceptions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Patching Third Party Libraries","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In general, this should be avoided. If you feel it is needed, please discuss with the dev community!","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Conventions within ","type":"text"},{"text":"Patching Third Party Libraries","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/AR/pages/18514306"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"New Public Methods and Classes","type":"text"}]},{"type":"paragraph","content":[{"text":"All new public methods and classes should have a @since annotation for the version when they were introduced. If the class is new, then it is enough to just put it at the class level instead of each method. Something like: @since","type":"text"},{"text":" 2.0","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Deprecation","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We deprecate methods that are part of our external public interface, instead of changing/deleting them in order to preserve backwards compatibility","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"External, public methods include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"service methods","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"public interface methods","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"domain object methods","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Internal methods are ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" considered public, and therefore do not have to go through a deprecation cycle, and can be changed/deleted outright. These include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"DAO methods","type":"text"}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We will delete all deprecated methods when we make a new version (e.g from 1.x to 2.0)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use both the @Deprecated annotation and the @deprecated javadoc comment","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The @deprecated javadoc annotation should point to the new method that is replacing the current one","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The @deprecated javadoc annotation should also mention the version when the deprecation happened. e.g: @deprecated As of 2.0, replaced by {@link #getEncounters(EncounterSearchCriteria)}","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Security","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Avoiding XSS scripting","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In JSPs, use a ","type":"text"},{"text":"core.OutTag","type":"text","marks":[{"type":"link","attrs":{"href":"http://docs.oracle.com/cd/E17802_01/products/products/jsp/jstl/1.1/docs/tlddocs/c/out.html"}}]},{"text":" for every string type attribute (or even for every variable)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: instead of this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"

${identifier.identifier} ${identifier.identifierType.name}

","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"write this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"

","type":"text"}]},{"type":"paragraph"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When using our custom \"openmrs:message\" or tag, make sure to use htmlEscape unless you ","type":"text"},{"text":"really","type":"text","marks":[{"type":"strong"}]},{"text":" need html/js tags in the message:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"

","type":"text"}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"StringEscapeUtils.escapeJavaScript() and StringEscapeUtils.escapeHtml() to escape any user-generated data in pages.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"StringEscapeUtils is an Apache class and its java doc can be found ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"http://commons.apache.org/proper/commons-lang/javadocs/api-2.6/org/apache/commons/lang/StringEscapeUtils.html"}}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the reference application (with the UI framework), use ui.escapeJs(), ui.escapeHtml(), and ui.escapeAttribute()","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Contextual Encoding is introduced for platform 2.0 and above.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead of StringEscapeUtils.escapeJavaScript() use WebUtil.encodeForJavaScript()","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead of StringEscapeUtils.escapeHtml() use WebUtil.escapeHTML() (This method signature is different from other signatures to preserve backward compatibility)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the variable is used for an html attribute use WebUtil.encodeForHtmlAttribute()","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You can find out the WebUtil class from ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-core/blob/master/web/src/main/java/org/openmrs/web/WebUtil.java"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OWASP Encoder java doc can be found ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"http://owasp-java-encoder.googlecode.com/svn/tags/1.1/core/apidocs/org/owasp/encoder/Encode.html"}}]},{"text":".","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Perfomance Optimization","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Java API level ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"String Builder (or StringBuffer) ","type":"text","marks":[{"type":"strong"}]},{"text":" rather than the ","type":"text"},{"text":" + Operator","type":"text","marks":[{"type":"strong"}]},{"text":" when concatenating String use this","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"StringBuilder x = new StringBuilder(\"a\");\nx.append(\"b\");","type":"text"}]},{"type":"paragraph","content":[{"text":" instead of ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"String s = \"a\"; \n s = s.concat(\"b.\"); ","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":" This saves memory space by avoiding creating new unnecesary objects hence reducing on extra","type":"text"},{"text":" pressure put on the GC. see above concatenating Strings ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222635"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid","type":"text"},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"BigInteger","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" and ","type":"text"},{"text":"BigDecima","type":"text","marks":[{"type":"strong"}]},{"text":"l ","type":"text"},{"text":"BigInteger","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"and","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"BigDecimal","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"require much more memory than a simple","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"long","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"or","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"double","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"and slow down all calculations dramatically. ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use","type":"text"},{"text":" primitives","type":"text","marks":[{"type":"strong"}]},{"text":" where possible Rather than ","type":"text"},{"text":"Wrapper classes ","type":"text","marks":[{"type":"strong"}]},{"text":" Another quick and easy way to avoid any overhead and improve the performance of your application is to use primitive types instead of their wrapper classes. So, it’s better to use an","type":"text"},{"text":" ","type":"text"},{"text":"int","type":"text","marks":[{"type":"em"},{"type":"strong"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"instead of an","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"Integer","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":",","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"or a","type":"text"},{"text":" ","type":"text"},{"text":"double","type":"text","marks":[{"type":"em"},{"type":"strong"}]},{"text":" ","type":"text"},{"text":"instead of a","type":"text"},{"text":" ","type":"text"},{"text":"Double","type":"text","marks":[{"type":"em"},{"type":"strong"}]},{"text":". That allows your","type":"text"},{"text":" ","type":"text"},{"text":"JVM","type":"text","marks":[{"type":"link","attrs":{"href":"https://stackify.com/jvm-metrics/"}}]},{"text":" ","type":"text"},{"text":"to","type":"text"},{"text":" ","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.javaworld.com/article/2150208/java-language/a-case-for-keeping-primitives-in-java.html"}}]},{"text":"store the value in the stack instead of the heap","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.javaworld.com/article/2150208/java-language/a-case-for-keeping-primitives-in-java.html"}}]},{"text":" ","type":"text"},{"text":"to reduce memory consumption and overall handle it more efficiently. ","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start"},"content":[{"type":"media","attrs":{"alt":"That allows your JVM to store the value in the stack instead of the heap to reduce memory consumption and overall handle it more efficiently.","type":"external","url":"https://stackify.com/wp-content/uploads/2017/10/https-lh6-googleusercontent-com-qaadmrc1c1mr83-e.png"}}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Make use of Use ","type":"text"},{"text":"Apache Commons String Uitils","type":"text","marks":[{"type":"link","attrs":{"href":"https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html"}}]},{"text":" for String operations as much as possible This library contains more efficient string operations functionalities which may greatly optimize Application Performance","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cache","type":"text","marks":[{"type":"strong"}]},{"text":" expensive resources Caching is a popular solution to avoid the repeated execution of expensive or frequently used code snippets. The general idea is simple: Reusing such resources is cheaper than creating a new one over and over again. A typical example is caching database connections in a pool. The creation of a new connection takes time, which you can avoid if you reuse an existing connection. see ","type":"text"},{"text":"Caching in openmrs","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/Caching+service+methods"}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Openmrs API Level","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid Fetching all resources in a single method call eg avoid calls like ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"getAllPatients();","type":"text"}]},{"type":"paragraph","content":[{"text":" If a database has more than 10k patients, this will probably cause an Out of Memory Error","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"paragraph","content":[{"text":"https://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/","type":"text","marks":[{"type":"link","attrs":{"href":"https://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/"}},{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph"},{"type":"paragraph"}],"version":1}