--- a/ssm-en.xhtml Wed Aug 31 11:45:16 2016 +0200
+++ b/ssm-en.xhtml Wed Nov 28 17:13:23 2018 +0100
@@ -26,6 +26,7 @@
<h2>Documented</h2>
<ul>
<li>At least basic documentation must be released under a free license (GNU FDL is recommended).</li>
+ <li>Every advertised feature must be properly documented. Undocumented features can not be considered as features from the user/customer point-of-view.</li>
<li>There might be also other documentation/books released under any license and price.</li>
<li>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</li>
<li>There must be a free documentation with description of building and running the software on a fresh operating system installation including description of all dependencies.</li>
@@ -42,7 +43,7 @@
<li>If there is a need of some marketing or cool versioning/codenames like Ultrasonic Umbrella or 2016, they should be used in addition to semantic versioning, not instead of it.</li>
<li>Once publicly released, the package must not be changed anymore – if a change (even a small fix) is needed, new version number must be assigned.</li>
<li>
- APIs, file formats and protocols might be semanticly versioned independently from the implementation;
+ APIs, file formats and protocols might (and usually should) be semanticly versioned independently from the implementation;
in such case, there should be a table documenting which API/format/protocol version matches which implementation version.
</li>
</ul>
@@ -53,13 +54,13 @@
<li>Don't broke things – rather postpone the release date than deliver a faulty product.</li>
<li>Don't remove features unless they are really obsolete, unused or unrepairably broken.</li>
<li>Incompatible changes must be planned and announced in advance. <!--Major/minor/patch numbers must be increased according to the Semantic versioning.--></li>
- <li>upgrade scripts + upgrade documentation</li>
+ <li>Upgrade scripts and upgrade documentation must be provided.</li>
</ul>
<h2>Compatible with others</h2>
<ul>
<li>use open standards (protocols, formats) if they exist</li>
- <li>define own open standards if needed
+ <li>define and publish own open standards if needed
<ul>
<li>also standards must be semantically versioned</li>
<li>should be written in machine readable format (WSDL, WADL, ASN.1, XSD, Diameter dictionary etc.) or at least formal language (Backus–Naur Form, EBNF etc.)</li>
@@ -82,11 +83,11 @@
<li>able to be extended
<ul>
<li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li>
- <li>by scripting (Guile, Bash, ECMA Script etc.)</li>
+ <li>by scripting (Guile, Bash, Python, Lua, ECMA Script etc.)</li>
<li>and/or third-party plugins/modules
<ul>
<li>it should be easy to create a third-party module and plug it in an existing system</li>
- <li>dependencies needed to write an extension (i.e. header files, API classes/interfaces) should be as small as possible (do not require large codebase to write a mere plug-in)</li>
+ <li>dependencies needed to write an extension (i.e. header files, API classes/interfaces) should be as small as possible (do not require large codebase to write a mere plug-in); the required dependency should contain just interfaces (method/function signatures) and data structures but no implementation (executable code)</li>
</ul>
</li>
</ul>
@@ -99,6 +100,7 @@
<li>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</li>
<li>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</li>
<li>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</li>
+ <li>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</li>
</ul>
<h2>Safe code and sustainability</h2>
@@ -106,8 +108,9 @@
<li>correctness, safety and readability is prefered to performance</li>
<li>use strong data typing, declare preconditions and possible exceptions</li>
<li>data structures must be known and well documented – don't use undocumented map keys or properties</li>
- <li>code, comments and analysis should be written in the same natural language</li>
+ <li>code, comments and specification should be written in the same natural language</li>
<li>there should be a dictionary of used terms, so whole team and also users and customers will speak same language</li>
+ <li>fail fast – errors in the code should be reported during build time or at least on first execution – don't silently continue if given error would lead to failure later in another part of the code – bad weak coupling leads to difficult debugging</li>
</ul>
<h2>Small code footprint</h2>