From 144e77a2212b2d2f0e3bd689fd7dc231d86a07a6 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 28 Mar 2020 17:23:21 +0100 Subject: Add initial development guide --- DEVELOPMENT.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 DEVELOPMENT.md (limited to 'DEVELOPMENT.md') diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..0e677eb --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,40 @@ +# MIDIMonster development guide + +This document serves as a reference for contributors interested in the low-level implementation +of the MIDIMonster. It is currently a work in progress and will be extended as problems come +up and need solving ;) + +## Basics + +All rules are meant as guidelines. There may be situations where they need to be applied +in spirit rather than by the letter. + +### Architectural guidelines + +* Change in functionality or behaviour requires a change in documentation. +* There is more honor in deleting code than there is in adding code. +* The `master` branch must build successfully. Test breaking changes in a branch. +* Commit messages should be in the imperative voice ("When applied, this commit will: "). +* The working language for this repository is english. + +### Code style + +* Tabs for indentations, spaces for word separation +* Lines may not end in spaces or tabs +* There should be no two consecutive spaces (or spaces intermixed with tabs) +* There should be no two consecutive newlines +* All symbol names in `snake_case` except where mandated by external interfaces +* When possible, prefix symbol names with their "namespace" (ie. the relevant section or module name) +* Variables should be appropriately named for what they do + * The name length should be (positively) correlated with usage + * Loop counters may be one-character letters + * Prefer to name unsigned loop counters `u` and signed ones `i` + +#### C specific + +* Prefer lazy designated initializers to `memset()` +* Avoid `atoi`/`itoa`, use `strto[u]l[l]()` and `snprintf()` + +## Architecture + +TBD -- cgit v1.2.3 From 126d9945eb3f4289975198b7437defb8bb13be73 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 28 Mar 2020 23:32:39 +0100 Subject: Extend development guidelines --- DEVELOPMENT.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'DEVELOPMENT.md') diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0e677eb..90c63ce 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -13,9 +13,12 @@ in spirit rather than by the letter. * Change in functionality or behaviour requires a change in documentation. * There is more honor in deleting code than there is in adding code. + * Corollary: Code is a liability, not an asset. + * But: Benchmark the naive implementation before optimizing prematurely. * The `master` branch must build successfully. Test breaking changes in a branch. * Commit messages should be in the imperative voice ("When applied, this commit will: "). * The working language for this repository is english. +* External dependencies are only acceptable when necessary and available from package repositories. ### Code style @@ -29,11 +32,14 @@ in spirit rather than by the letter. * The name length should be (positively) correlated with usage * Loop counters may be one-character letters * Prefer to name unsigned loop counters `u` and signed ones `i` +* Place comments above the section they are commenting on + * Use inline comments sparingly #### C specific * Prefer lazy designated initializers to `memset()` -* Avoid `atoi`/`itoa`, use `strto[u]l[l]()` and `snprintf()` +* Avoid `atoi()`/`itoa()`, use `strto[u]l[l]()` and `snprintf()` +* Avoid unsafe functions without explicit bounds parameters (eg. `strcat()`). ## Architecture -- cgit v1.2.3 From 3c6d2ccce4dd9be3f6497fb75d0456900e16ab0c Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 29 Mar 2020 11:28:44 +0200 Subject: Reschedule sacn frame output on EAGAIN --- DEVELOPMENT.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'DEVELOPMENT.md') diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 90c63ce..495c4f9 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -41,6 +41,8 @@ in spirit rather than by the letter. * Avoid `atoi()`/`itoa()`, use `strto[u]l[l]()` and `snprintf()` * Avoid unsafe functions without explicit bounds parameters (eg. `strcat()`). -## Architecture +# Build pipeline -TBD +# Architecture + +# Debugging -- cgit v1.2.3