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:

  1. Ask for reviews early and often
  2. We review both source code and test code (incl integration test code, devops code, documentation, all of it)
  3. Approach reviewing as an important part of the process – as a part of making things together.
  4. 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.
  5. 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.
  6. 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 changeBranch format
Featurefeature/PROJECT-12345
Bugbug/PROJ-12346
Hotfixhotfix/PROJ-12347Ideally never used
Releaserelease/<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.

%d bloggers like this: