4. Software Development

4.1 Choosing a programming language

The system being built must be written in one of the following languages. Exceptions are allowed where the industry standard deviates from the following list or there are dependencies which require a specific language to be used. (Eg. Python for data analytics.)

4.1.1 Backend

Go
Java
Python
Typescript

4.2 Web Frontend Framework

As browsers work with HTML, js and css, this section is only applicable when doing a Single Page Application (SPA). If doing server side rendering, this section can be skipped.

VueJS is the framework of choice. Please discuss with the project owner should there be a need to deviate from it.

4.3 Style guides

Having a consistent style within an organization ensures that different developers coming into the project will have an easier time picking it up, reducing the cognitive load on the developer.

As code style is a matter of preference, we have chosen to lean heavily on the code styles developed by the community of the different languages and frameworks.

You may also want to review MAMPUs guidance on coding style which can be found here.

4.3.1 Go

Code formatting in go is handled by the built in command go fmt.

Aside from that, Effective Go provides best practices on writing idiomatic go code.

4.4 Building with accessibility in mind

Government services must be accessible to everyone. This includes anyone with a visual, hearing, speech, motor or learning impairment. This also includes anyone with a temporary or situational disability, such as a person with a broken arm or working in a loud environment.

Building a service with accessibility in mind not only allows those with access needs to use your service, it also improves the service for everyone else. An accessibility problem with a website can be something that affects everyone, not just people who can only access the web with a keyboard or screen reader.

If your service is not accessible to everyone there can be cost implications too. Users who cannot access your service online will attempt to interact with the service in a way which is more costly for your organisation. (e.g. over the phone or face to face).

4.4.1 How to make your service accessible

Consider accessibility from the start

You cannot achieve accessibility by adding some final touches - it must be considered at all stages of a project. You should review designs for possible issues, write and run tests throughout development, and test services with accessibility in mind.

Understand that not everyone reads content the same way

A sighted user might navigate a page from top to bottom, perhaps skim reading through headings and paragraphs to find the content they want.

Non-sighted users can also skim read a page. Screen readers can announce content by element type, such as headings, paragraphs or links. For example, if a screen reader user expects a page to contain data in a table element, such as a train timetable, they might start by reading through all the tables on a page.

This is why semantic markup and good heading structure are important when building accessible services.

4.5 Documenting decisions

You should record decisions that affect the architecture of your service, in order to preserve the context of your choices.

As agile projects age, it is sometimes hard to keep track of the reasoning behind the decisions made. This is especially true as new people join the projects when those involved in the early stages are no longer around.

It is important to preserve the reasoning so the current team can include it as context when making their own decisions about changes they need to make. For example, understanding whether a particular choice was made for the sake of expediency and can therefore be changed with little impact, or whether there were external reasons behind that decision that need to be factored in.

4.5.1 How to document decisions

Architecture decisions should be stored in version control so there is a record of what was changed, who by, and when. Decisions that affect a specific application should be in that application’s code repository. You may also want to store larger-scale decisions in a central documentation repository.

A suggested format is the Architecture Decision Record, proposed by Michael Nygard in a blog post and since adopted widely. That post describes the format in full, but as a summary it consists of the following sections:

Title

A description of the decision (not the problem)

Status

eg Proposed, Accepted, Superseded

Context

The facts behind the need to make the decision

Decision

What the team has decided to do

Consequences

Both positive and negative consequences of the decision