Code Standards and Conventions
Original Author: Sumon C, May 27, 2021
Overview
This chapter outlines the standards and coding conventions that we follow at REDCap@Yale while developing external modules and other software.
Git Branching Conventions
At REDCap@Yale, we treat the main branch of the central repository as the "bleeding edge" version of the software, where all bug fixes, new features, and enhancements will be centrally incorporated. Various releases and versions will be created by branching off of this main branch.
Git Commit Message Conventions
REDCap@Yale recommends following the Conventional Commits specification, although this is not strictly necessary.
Messages should describe changes contained in the commit with present-tense action verbs. If there are multiple changes contained in a commit, or the description becomes too long for a single subject line, summarize the change in the first sentence, and then write lengthier descriptions underneath in the commit message using your text editor or IDE.
Semantic Versioning
REDCap External Modules are add-on packages of software that can extend REDCap's current functionality, as well as provide customizations and enhancements for REDCap's existing behavior and appearance, either at the system level or project level. Each external module exists or is added under the module directory of a REDCap instance. The semantic version of each module -either in the format _v0.0.0 or _v0.0- must be appended to the end of the directory for the EM Framework to recognize it is a module.
At REDCap@Yale, we follow the version number format MAJOR.MINOR.PATCH, where the following edits and revisions in software warrant changed in the version number:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
Version numbers should also be entered in config.json for each module, with a short summary of each version.
Examples
Initial development versions should start with 0.1.0, once the first feature for the module is developed.
In the announcement-banner module developed by REDCap@Yale, the following versions were created during development:
"0.0.1": "First version copied over from PC's 'HelloWorld' module",
"0.1.0": "Initial dev1 testing version",
"0.2.0": "Aesthetically complete version",
"0.3.0": "Version with cross-instance compatibility",
"1.0.0": "First production version deployed on all four instances"
Each MINOR version update represents a new feature added by the developer. Once released to the public (and/or deployed on production instances), the MAJOR version was incremented.
Most development efforts will result in an incremented PATCH version, if applying a fix to a bug, or an incremented MINOR version, when new features or functionality are added to a module. In these cases, a user may revert the external module to an earlier version and have no issues utilizing the module in REDCap.
A MAJOR version incrementation will be required when a user must upgrade to the new version in order to continue using the module in a REDCap project. These may be due to form changes that require the developer to update the SQL query required to access the data, or the use of a completely new plugin or dashboard that requires the user to relearn a workflow.
PHP Style Guides
Basic PHP styling is outlined here.
Further styling conventions that build on the basic PHP styling is outlined here.
JavaScript Style Guides
Google's source code style guide for JavaScript can be found here.
Airbnb also has a style guide, but the differences are not readily evident.
There is also a JavaScript style guide, linter, and formatter, but it's effectiveness / safety has not been validated.