Documentation

Date

Version

Changes

Date

Version

Changes

2022-02-06

v1.0.0

 

Documentation is very important for keeping a good flow in your development process. It helps you onboard new developers with little effort. It makes it easier to share code and solutions between teams. For product development, documentation should be prioritized.

1.1 Documentation MUST be governed and updated so it doesn’t become outdated.

1.2 Documentation SHOULD be written and governed together with the thing it documents.

1.3 Outdated documentation SHOULD be deleted. Example, project documentation once the project has been finished.

2 Code Documentation

2.1 Code SHOULD be documented as code comments.

2.2 Code comments SHOULD include information that you cannot decipher by reading the code.

Here follows examples of what should be documented as code comments.

2.2.1 Document why the code was written.

1 2 3 // On macOS it's common to re-create a window in the app when the // dock icon is clicked and there are no other windows open. if (BrowserWindow.getAllWindows().length === 0) createWindow();

2.2.2 Document your intention with the cod. This makes it easier to troubleshoot when the code doesn’t do what's intended.

1 2 3 4 5 6 // This method will be called when Electron has finished // initialization and is ready to create browser windows. // Some APIs can only be used after this event occurs. app.whenReady().then(() => { createWindow(); });

2.2.3 Document the obvious paths you tried but didn’t work. This will help the next person from falling into the same trap.

1 2 // DO NOT UNCOMMENT SHIT LINE, IT IS EVIL // import "core-js/es/object";

2.2.4 Document an explanation of what is going on when the code itself isn’t clear enough.

1 2 3 4 5 6 if (publicUrl.origin !== window.location.origin) { // Our service worker won't work if PUBLIC_URL is on a different origin // from what our page is served on. This might happen if a CDN is used to // serve assets; see https://github.com/facebook/create-react-app/issues/2374 return; }

2.2.5 Document a reference to the bug or issue that caused the change.

1 2 3 4 5 6 7 8 Sentry.init({ dsn: process.env.SENTRY_INGEST_URL integrations: [new Integrations.BrowserTracing()], // BUG AB#3133 Decrease sample rate in production // Decreasing sample rate to keep costs down. tracesSampleRate: 0.1, });

2.2.6 Document a description and parameters of public modules and functions.

1 2 3 4 5 6 7 8 9 10 /** * A button that let's you copy the current value to clipboard. * * @param {object} props * @param {string} props.text - The text to display on the button. * @param {string} props.value - The value to copy to clipboard. * @param {boolean} [props.isDisabled] - Whether the button should be disabled. */ function CopyButton({ text, value, isDisabled = false }) { }

2.2.7 Document the source of information that the code was created from.

1 2 3 4 5 /** * The source for these abbreviations is here. * https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations */ let abbreviations = ["aks", "appcs", "ase", "plan", "appi", "apim", ....];

2.2.8 Document the source of copy/pasted code.

1 2 3 4 5 6 7 8 // source: https://stackoverflow.com/a/15289883 function dateDiffInDays(a, b) { // Discard the time and time-zone information. const utc1 = Date.UTC(a.getFullYear(), a.getMonth(), a.getDate()); const utc2 = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate()); return Math.floor((utc2 - utc1) / _MS_PER_DAY); }

2.2.9 Document where you can find more information about a topic.

1 2 3 4 5 // Official DCC Schema documentation // https://github.com/ehn-dcc-development/ehn-dcc-schema function parseDccSchema(dcc) { /** implementation... */ }

2.2.10 Document results that are not visible in the code.

1 2 3 4 5 6 7 8 /** * Calculator screen. It is divided into a left and right part, where the left part * is the input form and the right part presents the result. If the screen width is * less than 768px the left part becomes top and the right part becomes the bottom. */ function Calculator() { /** implementation.. */ }

2.3 Documentation SHOULD NOT include previous implementations of the code. Reference to the commit history if the previous implementation is important.

2.4 Documentation SHOULD be verified as part of a pull request workflow.

3 Repository Documentation

3.1 The code repository MUST contain a README.md file in the root directory that include how to setup a development environment, how to run the code, how to run the tests and references to more documentation, example a wiki page or product page.

3.2 The code repository MAY contain a README.md file in a directory about the content in that folder. Example, the contents of the directory is automatically generated by the build script.

3.3 The code history SHOULD have commit messages referencing to issues. See separate article on version controlling your source control.

4 System Documentation

4.1 System documentation SHOULD be hosted on a wiki platform that is easy to modify and update.

4.2 System documentation MUST describe the system and how it fits into the system landscape.

4.3 System documentation SHOULD refer to where the code repository for the system is hosted.

4.4 System documentation SHOULD refer to environments where the system is hosted.

4.5 System documentation SHOULD refer to people involved in building and maintaining the system.

4.6 System documentation MUST include a release log.