moj-analytical-services / our-coding-standards Goto Github PK

• What information should be in a README?
• How and to what extent should we document our functions?

Would be good to have examples of hopping around branches, and reverting adds/commits? Also rebasing- what's rebasing?

• Some notes on what this repo is for
• This is guidance rather than rules, but we should try to follow them
• If we think of something better than what is written here, it can be changed

• When should we test something manually?
• How far should this testing go?
• How will we record what has been tested?

• Eventually your code will need to work on another machine
• This could be a colleague's computer or a server somewhere
• We, therefore, need to ensure the code will work in these environments
• How can we do this (in addition to the normal QA process)?

• Why is it useful?
• When is it appropriate?
• What tools should we use?
• Some examples

If we write some nice functions that perform useful tasks which we might want to use again and share with other people (for example, I wrote something at the weekend which extracts the names of the most significant features from a regression model and trains a new model using only those features*), where should we keep them? Should they all be in one repo? Or one for each language we're using? How should the functions be name spaced within that repo? Are they each in their own package?

* I will not be the slightest bit surprised if someone points out that this has already been done by someone else! ;)

It would be useful to have more specific naming conventions, for variables, file names, branches (?), etc.

• There is a rich catalogue of packages, some of which have their own syntactic and functional quirks
• So that people can move around easily from one project to another, we should agree on a set of sensible default packages
• These sensible defaults should also 'play nicely together'; they should be highly compatible with one another

• High level coding principles that describe what is and isn't OK
• We can take inspiration from Digital's equivalent

• Is there a recommended procedure for carrying out peer review?
• What is the minimum set of checks for something to be considered peer reviewed?
• What happens when you disagree with your reviewer's comments?

There's good guidance on how to branch, commit, etc. Also useful would be when to do these things, and/or why.

Hi there

The user nikki-rayner had Direct Member access to this repository and access via a team.

Access is now only via a team.

You may have less access it is dependant upon the teams access to the repo.

If you have any questions, please post in #ask-operations-engineering on Slack.

This issue can be closed.

in README_template.md the link AQA checklist markdown is broken, returns error 404

As part of improving knowledge sharing across the team we want to improve the README and tagging of projects.

README:

• What makes a good README?
• Approach the README as if it were going to be a public repo - focus on how you would explain the project to someone coming to the project for the first time.
• Include brief description of the high level aim, basic outline of what techniques are used, list main packages for usage

Tagging:

• customer/project area
• key packages
• key techniques

• How should we structure our applications so that new contributors know where to find things?
• How should we name files (for the same reason as above)

• What flow should we use?
• How and when does QA happen during this process?

• For larger projects, it's recommend that there is protected master branch is enforced. This will ensure short lived branches which are merged often.

• Set up and recommend a specific R linter that everyone uses. Makes sure it's fairly lax.

• Possibly re-instate code smells. (e.g. use R projects)

• Large data files should not be version controlled
• By convention, they should also be stored separately from the application that consumes them
• This allows the data and application to be updated independently
• This also allows multiple instances of the same application to access a single canonical data set
• It would be helpful to have a standardised solution for this

• To work on the analytics platform you must manage R package dependencies using PackRat
• How should we manage OS dependencies?

Should we have rough guidelines as to what constitutes a large, medium, small project?

Starter for 10:
Small - a working version is built in a week, <300 lines of code, all code sensibly contained in one file
Medium - a working version is built in a month, < 800 lines of code, may contain multiple (code) files
Large - a working version takes more than a month, >800 lines of code

Minimum standard - having gone through the ethnical framework