Coding Conventions

[jmiranda]

Draft of coding conventions

Resources

• https://tedvinke.wordpress.com/2015/03/15/basic-groovy-and-grails-code-review-guidelines/
• https://github.com/topics/coding-conventions
• https://github.com/leapfrogtechnology/coding-guidelines

Codifying Coding Conventions

• https://wengier.com/codify-your-coding-standards/
• .editorconfig https://editorconfig.org/

Enforcing Coding Conventions

• Discuss linters, pre-commit hooks, github actions

Coding Convetions

REST APIs

• Use REST conventions (i.e. resource names, request method determines action)
• Avoid remote procedure call naming convention for APIs OBAM-178 Create association between order and picklist #2623 (comment)

Style Guides (to be considered)

Groovy

• https://groovy-lang.org/style-guide.html

Java

• Google https://google.github.io/styleguide/javaguide.html
• Standard https://www.oracle.com/java/technologies/javase/codeconventions-contents.html

JSON

• JSON https://google.github.io/styleguide/jsoncstyleguide.xml

JavaScript

• ???

Typescript

• Google TypeScript Style Guide - TypeScript Style Guide used at Google's.
• Typescript deep dive - Style Guide - An unofficial TypeScript Style Guide.
• Typescript Lang - Do's and Don'ts - Suggestions from Typescript Lang organization.

React

• ???

[jmiranda]

I was hoping that we could link to this discussion from other tickets / PRs and then those references would show up here. That way we could have a compilation of all of the comments that need to be codified as coding conventions. However, I'm not seeing them so I'm going to have to figure out the right approach.

[jmiranda]

Proposal

We want to be able to be able to collect coding conventions (and tech huddle topics, etc) in one place without requiring someone to disrupt what they are doing and add the convention / topic to a central public repository (i.e. coding conventions document in GH). The reason to not do this is 1) it's disruptive 2) we don't want just anyone to add coding conventions without review.

Instead, the idea would be that we'd allow the developer or stakeholder to annotate their comments with a link to an issue, discussion, label to indicate their preference to include the comment as a convention. Then as part of a separate process a developer who is responsible for coding conventions could review these comments and add them to the central repository.

Solution 1 Reference a Discussion Number

Unfortunately, this did not have the desired effect. There's no back reference created in the discussion (from the issue or PR) so the only way to collect the coding conventions is to do a search for discussion #3849 in the Issue Search.

Doing the search under Pull Requests is similar but does not include issues so not as useful.

Solution 2 Reference an Issue Number

Referencing the "Document coding convention" ticket (#3867) in PRs has the desired effect. We can reference the issue number in a specific comment that we think should be converted into a coding convention.

Solution 3 Apply a "coding convention" label to the Pull Request or Issue

That way if we wanted to reference a label you could add the following URL to the markdown
https://github.com/openboxes/openboxes/labels/documentation
and it would automatically render as a label.
documentation

That would link us to all issue with that label.

Not exactly what we're looking for but it's a start. The negative of this would be that we are applying the label to the whole PR / issue so a developer would need to parse all the comments to figure out which one refers to a coding convention. So we have some "falling through the cracks" potential here.

Solution 4 - Add an annotation plugin to browser (Chrome, Firefox) that would allow us to

Pros:

• We could annotate our own comments as well as coding conventions for other projects.
• All of these annotations would be available in a central place for review.
• Would potentially apply to more sources (code reviews, slack discussions, Jira tickets

Cons:

• We'd have to find a tool that works for all developers / environments.
• Every developer would have to install the plugin manually (as opposed to having a solution that works out of the box).

Other issues to consider

• This helps us with pull requests where most coding conventions would be covered.
• This would not help us with discussions in Jira tickets and Slack conversations, so we might have to think

Resources

• Discussed during Retrospective for Sprint 106 https://easyretro.io/publicboard/16uR87jBo8dvYx1SuHmy0V4U1UN2/74103a1c-f4e8-4a92-b93f-7dc51b5c1db9
• Create a way to track coding conventions discussed during code reviews https://pihemr.atlassian.net/browse/OBS-1406
• Tech Huddle: Figure out the coding conventions and our approach to build it https://pihemr.atlassian.net/browse/OBPIH-5310
• Soldevelo coding conventions https://pihemr.atlassian.net/wiki/spaces/OB/pages/2703294465/25+Jan+2023+-+TH
• https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file
• https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors