--- a/text/ssm.en.xml Sun Oct 06 09:28:14 2019 +0200
+++ b/text/ssm.en.xml Sun Oct 06 22:12:47 2019 +0200
@@ -311,25 +311,26 @@
<type>information</type>
<text>Tests verify the compliance of the implementation with the documentation or specification.</text>
</item>
+ <!-- TODO: the software should be structured in a way which facilitates writing tests – e.g. separate the UI from the core and allow calling the core functions from the tests – which has also other positive side effects -->
<item>
<id>d95dc118-7473-4f18-8b9e-35830a87b269</id>
<type>recommendation</type>
- <text>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</text>
+ <text>There should be automated build-time complex tests for the package. The test feeds the program with sample input and verifies expected output.</text>
</item>
<item>
<id>a9f6725d-ddf1-41ee-96b4-15f3b851cb50</id>
<type>recommendation</type>
- <text>there should be also automated runtime/postinstall tests – in order to verify that software was installed properly, all required dependencies are met and basic function is guaranteed – the program should report problem during its start (as a warning if it is not fatal), instead of unexpected failures during operation</text>
+ <text>There should be also automated runtime/postinstall tests – in order to verify that software was installed properly, all required dependencies are met and basic function is guaranteed – the program should report problem during its start (as a warning if it is not fatal), instead of unexpected failures during operation.</text>
</item>
<item>
<id>d610c04b-cc44-48c7-b069-f41b90bdef0f</id>
<type>recommendation</type>
- <text>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</text>
+ <text>Unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces.</text>
</item>
<item>
<id>e85baeda-8fcb-42d1-bb53-d7386a941ae7</id>
<type>recommendation</type>
- <text>each external interface should contain procedure/function that does nothing important or heavy, is idempotent and returns simple response which proves that the interface (connection) is working (e.g. echo, print version, status or current time); if authentication and authorization mechanisms are present, there should be one procedure/function callable anonymously and one that requires authorization</text>
+ <text>Each external interface should contain procedure/function that does nothing important or heavy, is idempotent and returns simple response which proves that the interface (connection) is working (e.g. echo, print version, status or current time). If authentication and authorization mechanisms are present, there should be one procedure/function callable anonymously and one that requires authorization.</text>
</item>
</chapter>
@@ -339,22 +340,22 @@
<item>
<id>a96206c9-3e69-483d-b575-6bab9dec4a30</id>
<type>requirement</type>
- <text>correctness, safety and readability is preferred to performance</text>
+ <text>Correctness, safety and readability is preferred to performance.</text>
</item>
<item>
<id>d8eba0dd-4305-44b9-80ea-4c38b6dfa633</id>
<type>recommendation</type>
- <text>use strong data typing, declare preconditions and possible exceptions</text>
+ <text>Strong data typing should be used, preconditions and possible exceptions should be declared in the interface and they are part of the contract.</text>
</item>
<item>
<id>ebea0c16-f820-444d-a73c-3054ca6a38c8</id>
<type>requirement</type>
- <text>data structures must be known and well documented – do not use undocumented map keys or properties</text>
+ <text>Data structures must be known and well documented. Do not use e.g. undocumented map keys or properties.</text>
</item>
<item>
<id>e24e600e-6542-4664-8cf0-2d8c6feb6c13</id>
<type>recommendation</type>
- <text>code, comments and specification should be written in the same natural language</text>
+ <text>Code, comments and specification should be written in the same natural language.</text>
<link>
<url>https://www.gnu.org/prep/standards/standards.html#Comments</url>
<type>related</type>
@@ -365,12 +366,12 @@
<item>
<id>fa92aa33-a69f-43b8-9051-9bfdcd3d293f</id>
<type>recommendation</type>
- <text>there should be a dictionary of used terms, so whole team and also users and customers will speak the same language</text>
+ <text>There should be a dictionary of used terms, so whole team and also users and customers will speak the same language.</text>
</item>
<item>
<id>b9345a0e-c672-45d3-b93b-8d0fb4ece8b3</id>
<type>recommendation</type>
- <text>fail fast – errors in the code should be reported during build time or at least on first execution – do not silently continue if given error would lead to failure later in another part of the code – bad weak coupling leads to difficult debugging</text>
+ <text>Fail fast – errors in the code should be reported during build time or at least on first execution – do not silently continue if given error would lead to failure later in another part of the code – bad weak coupling leads to difficult debugging.</text>
</item>
</chapter>
@@ -380,17 +381,17 @@
<item>
<id>f5389468-2f8a-43c8-884a-8df6bc844453</id>
<type>recommendation</type>
- <text>less LOC (resp. cyclomatic complexity) = better</text>
+ <text>Less LOC (resp. cyclomatic complexity) = better.</text>
</item>
<item>
<id>b6b6c838-be6d-43d5-9f99-2098fa217c54</id>
<type>recommendation</type>
- <text>reduce boilerplate and unused code</text>
+ <text>Boilerplate and unused code should be reduced. Adequately high-level programming language or framework should be used.</text>
</item>
<item>
<id>b07fe0f0-2be7-4c1c-9b19-b671269c5e58</id>
<type>recommendation</type>
- <text>use code generators (during build process, not to generate code to be manually edited and versioned)</text>
+ <text>Code generators should be used (during the build process, not to generate code to be manually edited and versioned).</text>
<link>
<url>https://www.gnu.org/prep/standards/standards.html#Releases</url>
<type>compatible</type>
@@ -406,52 +407,48 @@
<item>
<id>c2d5a677-a721-40e3-b560-73afe76fe2b0</id>
<type>recommendation</type>
- <text>avoid NIH and reuse code but also avoid dependency hell</text>
+ <text>Avoid NIH syndrome and reuse code but also avoid dependency hell.</text>
+ <text>Complexity is defined by the complexity of the program itself + complexity of its dependencies.</text>
</item>
<item>
<id>d214987c-881c-450b-8544-82141866f541</id>
<type>requirement</type>
- <text>know your dependencies, know why they are required</text>
- </item>
- <item>
- <id>c8402612-e136-43b5-9209-f9800d2e94da</id>
- <type>recommendation</type>
- <text>reduce dependencies to only necessary ones</text>
+ <text>Know your dependencies, know why they are required.</text>
</item>
<item>
<id>cbeb9a6b-7b64-4452-8caf-246c082a853d</id>
<type>recommendation</type>
- <text>depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies</text>
+ <text>Depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies.</text>
</item>
<item>
<id>cbaf55be-8ffb-4109-9c83-083d1b3e793a</id>
<type>requirement</type>
- <text>if dependency on bulky application package is inevitable, add a layer of abstraction – create a generic interface and connector and allow others to replace the bulky package with their own sane implementation</text>
+ <text>If dependency on bulky application package is inevitable, add a layer of abstraction – create a generic interface and connector and allow others to replace the bulky package with their own sane implementation.</text>
</item>
<item>
<id>d7655989-a5e4-4123-9147-3782fc05a5ee</id>
<type>recommendation</type>
- <text>helper tools:</text>
+ <text>Complexity caused by helper tools should be also reduced:</text>
<item>
<id>a5307bc9-36ed-4d83-963a-30c5c67613aa</id>
<type>recommendation</type>
- <text>if you e.g. use Bash and Perl during the build process, do not add also Python dependency, write it in Perl – or use Python instead of Perl.</text>
+ <text>If you e.g. use Bash and Perl during the build process, do not add also Python dependency, write it in Perl – or use Python instead of Perl.</text>
</item>
<item>
<id>b0237d84-7068-4b2b-bc28-ce5e0a0061e4</id>
<type>recommendation</type>
- <text>Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it</text>
+ <text>Or if you use Java as your main language, consider not using Python/Perl for scripting and use some JVM language for it.</text>
</item>
</item>
<item>
<id>a0f42ec9-5032-4f6d-a50a-4b7bddde77f0</id>
<type>requirement</type>
- <text>if possible, always depend on abstract interfaces, not on particular implementations</text>
+ <text>If possible, always depend on abstract interfaces, not on particular implementations.</text>
</item>
<item>
<id>c5974dcd-4855-40c5-ad22-894c128ca1dc</id>
<type>recommendation</type>
- <text>from the whole system point-of-view, Bootstrappable builds should be taken into account</text>
+ <text>From the whole system point-of-view, Bootstrappable builds should be taken into account.</text>
<link>
<url>http://bootstrappable.org/</url>
<type>related</type>
@@ -466,18 +463,18 @@
<item>
<id>aeef6a5c-bafc-4fcf-9b21-5829e8a44c5e</id>
<type>recommendation</type>
- <text>small code footprint and minimal dependencies makes it easy to do security audit</text>
+ <text>Small code footprint and sane dependencies make it easier to do security audit.</text>
</item>
<item>
<id>ab69d352-da68-40c2-a3e1-a8fd5c41ad0a</id>
<type>recommendation</type>
- <text>avoid ungrounded refactoring and reformatting – they make mess and noise in the version control system and impede the audit</text>
+ <text>Ungrounded refactoring and reformatting should be avoided – they make mess and noise in the version control system and impede the audit.</text>
<note>This rule is classified as a recommendation only because of the fact that past mistakes usually can not be reverted, which would disqualify the software forever. However it should be normally considered to be a requirement.</note>
</item>
<item>
<id>e4db77b8-f145-4e43-bf8b-eb775b9352c8</id>
- <type>information</type>
- <text>refactoring/reformatting changesets should be separated from substantive changes</text>
+ <type>recommendation</type>
+ <text>Refactoring/reformatting changesets should be separated from substantive changes.</text>
</item>
</chapter>
@@ -487,12 +484,12 @@
<item>
<id>e5154815-eeae-4664-8883-a29a64eea325</id>
<type>recommendation</type>
- <text>builds should be reproducible: same code/version → same binary package</text>
+ <text>Builds should be reproducible i.e. same code/version should lead to the same binary package.</text>
</item>
<item>
<id>a3b0c164-4dde-4e33-b3be-5478d2a187e2</id>
<type>requirement</type>
- <text>if not, it should be documented, why and how build products might differ, and there should be plan/task to make it reproducible</text>
+ <text>If they are not reproducible, it should be documented, why and how build products might differ, and there should be plan/task to make builds reproducible.</text>
</item>
</chapter>
@@ -502,32 +499,33 @@
<item>
<id>a0d9322c-7d2b-4632-b543-7e0d75bb5f0b</id>
<type>requirement</type>
- <text>every released version (binary or source) must be cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended)</text>
+ <text>Every released version (binary or source) must be cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended).</text>
</item>
<item>
<id>feb97ec0-c35c-49b8-b455-517a929b4a84</id>
<type>recommendation</type>
- <text>there should be also checksums/hashes for every released package</text>
+ <text>There should be also checksums/hashes for every released package.</text>
</item>
<item>
<id>ff33e209-0460-4a43-997f-d6b32b73997b</id>
<type>recommendation</type>
- <text>if HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user</text>
+ <text>If HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user.</text>
</item>
<item>
<id>c1f83b3a-e564-4483-91de-9c08723efd13</id>
- <type>recommendation</type>
- <text>the attacker should not be able to suppress updates – the program must not be silent in such case and must warn the user that something possibly nasty and dangerous is happening</text>
+ <type>requirement</type>
+ <text>The attacker must not be able to suppress updates – the program (usually a package management system) must not be silent in such case and must warn the user that something possibly nasty and dangerous is happening.</text>
+ <note>This is relevant mostly to distributions and package managers which should be used for updates (the application should not update itself).</note>
</item>
<item>
<id>c6a755c9-a54e-4ffb-8f70-bfbd851b93c5</id>
<type>recommendation</type>
- <text>releases should be downloadable also (or exclusively) over BitTorrent or other P2P network</text>
+ <text>Releases should be downloadable also (or exclusively) over BitTorrent or other P2P network.</text>
</item>
<item>
<id>f9275c3c-2b09-4aec-ac28-76ff827d52ce</id>
<type>requirement</type>
- <text>source code repository must be accessible through an encrypted connection</text>
+ <text>Source code repository must be accessible through a secure and encrypted connection.</text>
</item>
</chapter>