This is a sample ways-of-working document.
Language
We develop using Java x as a target.
Note that we’ll need to make sure our stuff will work with Java y – something to consider for some of our integration testing.
** consider latest commercially support versions.
Coding Standards
Java
For Java Development, we follow the TODO guide and the Google Java Style Guide and other references but avoiding slavish adherence to rules for no reason. (See more of this in code reviews below.)
Variations from these will be noted here. There are no variations at this time.
Our development is test-driven. We aim for competent and complete Unit-test coverage, but not to second guess the compiler or other tools that we use.
We expect that there will be some static analysis of our code.
Security
We architect and code to a relevant level of security. We care about and build secure systems that manage risk appropriately. We know how to evaluate risk and get sign off from our stakeholders.
- The OWASP Top 10 are worth considering: https://www.owasp.org/index.php/Top_10-2017_Top_10
- Careful with Input and Output encoding
- Careful with Input validation
- SEI CERT coding standards for Java at: ….
- Generally be conservative in code and implementation.
- Limit the use of ‘magic’ to well understood common cases. If in doubt, make it explicit even if doesn’t look as pretty or concise.
Code Reviews
Code reviews are part of the conversation we have together as a team as we build things. As a result, we:
- Ask for reviews early and often
- We review both source code and test code (incl integration test code, devops code, documentation, all of it)
- Approach reviewing as an important part of the process – as a part of making things together.
- As a reviewer, consider the big picture of the project, the needs of this code, and standards while looking for improvements and opportunities for learning together while making the codebase better.
- As a reviewer, be clear about what we want. Don’t ask a (passive-aggressive) question if you want to make a suggestion or improvement. NB the word “should” is often a marker of something that we’re not being clear about.
- Avoid pedantry – what Guido (author of Python) said in relation to Python coding standards: “A foolish consistency is the hobgoblin of little minds”. Don’t sweat the tiny details if our code is safe, effective and maintainable.
We’ll review as a compulsory part of the process when we raise a pull request against a release or master branch. This will involve our own review and usually some review from our other peers / developer colleagues. This will get more formal as we get further through our development processes.
Documentation in code
We aim to develop code that is mostly self-documenting by structure and style. We’ll use Javadoc where needed to explain things, or when we feel like we need to add more information. This doesn’t mean we never document anything. This does mean we document where necessary. Your judgement is needed.
Documentation separate from the code
README and other markdown files are welcome and useful to document building, testing and deployment instructions and to explain quirks or special arrangements in the source.
Commits
Commit messages are useful for later diagnosis and as a record of what and when and to a certain extent why.
To work with other tooling linking a commit to a story is a good idea. Then we can answer the question of what is in a release branch with a git log command. A commit might look like this:
PROJ-12345 #short description of the changes made.
where the PROJ-12345 is a JIRA story ID and the rest is a short description like the JIRA story title.
Commit as often as you like. We prefer changes to be logically grouped and kept to a few files per commit. Multiple commits per story are fine.
We prefer a full messy commit history to having history removed with re-basing. Commits are cheap, so let’s keep the history. Re-basing erases history and can cause problems if other branch users don’t know what is happening.
Stories
Each code change needs a JIRA story, and we use JIRA stories for naming branches.
Branches
| Type of change | Branch format | |
| Feature | feature/PROJECT-12345 | |
| Bug | bug/PROJ-12346 | |
| Hotfix | hotfix/PROJ-12347 | Ideally never used |
| Release | release/<tag> | This is if we use release branches, which can be annoying but are sometimes necessary. We’d tend to prefer delivering into master and have master releasable by a git tag indicating a release version. |
Mostly we’ll use features.
Process
We follow a Sprint-based scrum-like 2-week process, which may be more or less Scrum or Kanban-like, depending on the team.
Testing
We code unit tests to test significant functionality, not to second guess the compiler. General
Deployment
As continuous as it can be, accepting the restrictions in the deployment environment.