Developers Corner 2 – Software development standards

UpdatedOctober 18, 2023

By Peter Hutten-CzapskiPeter Hutten-Czapski

Some Standards for OSCAR 19 Software development

OSCAR 19 aka OSCAR EMR on bitbucket and OSCAR McMaster on sourceforge

the code managed by the copyright and trademark holder McMaster Department of Family Medicine

The Commandments

Thou Shall Pass Stylecheck

Your code must pass Stylecheck. Editing style check to allow your code that say uses Vectors to pass is not passing style check.

Thou Shall Release to GPL 2+

If you commit you are assigning to the department of family medicine please and thanks

There are other acceptable copyright header

(we have McMaster Indivica KAI U Vic CAISI and others as ones that pass stylecheck)

Regardless of copyright its all released open source GPL 2+

Thou Shall Set An ISSUE in Jira and Form a Branch

Following commits is a pain, but made easier if they are commented and grouped by issue and development branch

Thou Shall Craft Pull Requests That are Squash Merge

Squash merges are a bit easier to review.

Thou Shall Enable New Features By Default

Although if at all controversial or risky ensure that they can be turned off either by the global properties settings, and/or in Administration for system settings, and/or as individual preferences.

Thou Shall i18n

Do not break support for French and Brazillian Portugese by hard coding the UI in English. Google translate is your friend. Reference the bean for the property file key and you will be good. <bean:message key=”global.harmony” />

Thou Shall Assume the Schema is Corrupt

Do not trust that database entries are sanitized. Use OWASP encoding when displaying data in the JSP.

String serviceDesc = Encode.forHtml(dont.trust.me(cuz));

Thou Shall Respect Your Elder(ly framework)s

For consistency the UI should be using existing JQuery Twitter Bootstrap and other libraries when practical. Use the newer ones from the existing list. jQuery 3.6.4 pairs nicely with Datatables 1.13.4 and are both so 2023. You do not have to design UI for mobile devices but be mindful that from time to time OSCAR IS used on mobile. Do not use the older versions which are deprecated and are slowly being replaced in OSCAR. Do not commit newer versions without a good reason (a point release is NOT a good reason by itself) as it adds bloat, may impact look and feel and complicate future maintenance.

<link href="${pageContext.request.contextPath}/css/bootstrap.css" rel="stylesheet">
<link href="${pageContext.request.contextPath}/css/DT_bootstrap.css" rel="stylesheet">
<link href="${pageContext.request.contextPath}/css/bootstrap-responsive.css" rel="stylesheet">
<script src="${pageContext.request.contextPath}/library/jquery/jquery-3.6.4.min.js"></script>
<script src="${pageContext.request.contextPath}/library/DataTables/datatables.min.js"></script><!-- 1.13.4 -->

Thou Shall HTML 5 and use Struts To Make It Happen

If you are working in the UI there is a lot of quirks mode going on. It works but a HTML 5 validator such as provided at https://validator.w3.org will catch open tags and deprecated attributes. Generate the appropriate HTML code via struts TLD when possible.

<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html"%>
<!DOCTYPE html>
<html:html locale="true">
<title><bean:message key="perfect.title" /></title>
<html:base />
... head and body ...
</html:html>

Thou Shall Keep Java in a Class by itself

While technically you CAN put all your Java into a JSP, there is almost universal agreement that as a rule Java should sit in the backend and not the View. This makes it easier to debug and re-use. You can keep existing <% servlets %> in JSP files but they should not increase

Thou Shall Space

Yeah I’m a tabber too, that’s why its the last commandment. For consistency we had to fall on one side of the fence or another eventually and the spaces have it. By all means tab to make your code easier to read, however when you save your commit convert tabs to 4 spaces. To be precise “Five shalt thou not count, neither count thou three, excepting that thou then proceed to four. Six is right out.”