24 </ul> |
24 </ul> |
25 |
25 |
26 <h2>Documented</h2> |
26 <h2>Documented</h2> |
27 <ul> |
27 <ul> |
28 <li>At least basic documentation must be released under a free license (GNU FDL is recommended).</li> |
28 <li>At least basic documentation must be released under a free license (GNU FDL is recommended).</li> |
|
29 <li>Every advertised feature must be properly documented. Undocumented features can not be considered as features from the user/customer point-of-view.</li> |
29 <li>There might be also other documentation/books released under any license and price.</li> |
30 <li>There might be also other documentation/books released under any license and price.</li> |
30 <li>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</li> |
31 <li>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</li> |
31 <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> |
32 <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> |
32 <!-- |
33 <!-- |
33 <li>documentation should focus on all target groups: users, administrators, developers</li> |
34 <li>documentation should focus on all target groups: users, administrators, developers</li> |
40 <li><a href="http://semver.org/">Semantic versioning</a> is strongly recommended.</li> |
41 <li><a href="http://semver.org/">Semantic versioning</a> is strongly recommended.</li> |
41 <li>Especially when the software is suposed to be used as dependency by others.</li> |
42 <li>Especially when the software is suposed to be used as dependency by others.</li> |
42 <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> |
43 <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> |
43 <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> |
44 <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> |
44 <li> |
45 <li> |
45 APIs, file formats and protocols might be semanticly versioned independently from the implementation; |
46 APIs, file formats and protocols might (and usually should) be semanticly versioned independently from the implementation; |
46 in such case, there should be a table documenting which API/format/protocol version matches which implementation version. |
47 in such case, there should be a table documenting which API/format/protocol version matches which implementation version. |
47 </li> |
48 </li> |
48 </ul> |
49 </ul> |
49 |
50 |
50 <h2>Compatible with itself</h2> |
51 <h2>Compatible with itself</h2> |
51 <ul> |
52 <ul> |
52 <li>Focus on backward compatibility. Newer version should work as a drop-in replacement.</li> |
53 <li>Focus on backward compatibility. Newer version should work as a drop-in replacement.</li> |
53 <li>Don't broke things – rather postpone the release date than deliver a faulty product.</li> |
54 <li>Don't broke things – rather postpone the release date than deliver a faulty product.</li> |
54 <li>Don't remove features unless they are really obsolete, unused or unrepairably broken.</li> |
55 <li>Don't remove features unless they are really obsolete, unused or unrepairably broken.</li> |
55 <li>Incompatible changes must be planned and announced in advance. <!--Major/minor/patch numbers must be increased according to the Semantic versioning.--></li> |
56 <li>Incompatible changes must be planned and announced in advance. <!--Major/minor/patch numbers must be increased according to the Semantic versioning.--></li> |
56 <li>upgrade scripts + upgrade documentation</li> |
57 <li>Upgrade scripts and upgrade documentation must be provided.</li> |
57 </ul> |
58 </ul> |
58 |
59 |
59 <h2>Compatible with others</h2> |
60 <h2>Compatible with others</h2> |
60 <ul> |
61 <ul> |
61 <li>use open standards (protocols, formats) if they exist</li> |
62 <li>use open standards (protocols, formats) if they exist</li> |
62 <li>define own open standards if needed |
63 <li>define and publish own open standards if needed |
63 <ul> |
64 <ul> |
64 <li>also standards must be semantically versioned</li> |
65 <li>also standards must be semantically versioned</li> |
65 <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> |
66 <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> |
66 <li>also configuration should have machine readable description and should be testable by executing a command</li> |
67 <li>also configuration should have machine readable description and should be testable by executing a command</li> |
67 </ul> |
68 </ul> |
80 |
81 |
81 <ul> |
82 <ul> |
82 <li>able to be extended |
83 <li>able to be extended |
83 <ul> |
84 <ul> |
84 <li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li> |
85 <li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li> |
85 <li>by scripting (Guile, Bash, ECMA Script etc.)</li> |
86 <li>by scripting (Guile, Bash, Python, Lua, ECMA Script etc.)</li> |
86 <li>and/or third-party plugins/modules |
87 <li>and/or third-party plugins/modules |
87 <ul> |
88 <ul> |
88 <li>it should be easy to create a third-party module and plug it in an existing system</li> |
89 <li>it should be easy to create a third-party module and plug it in an existing system</li> |
89 <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> |
90 <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> |
90 </ul> |
91 </ul> |
91 </li> |
92 </li> |
92 </ul> |
93 </ul> |
93 </li> |
94 </li> |
94 <li>there should be public directory of extensions/scripts</li> |
95 <li>there should be public directory of extensions/scripts</li> |
97 <h2>Testable</h2> |
98 <h2>Testable</h2> |
98 <ul> |
99 <ul> |
99 <li>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</li> |
100 <li>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</li> |
100 <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> |
101 <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> |
101 <li>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</li> |
102 <li>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</li> |
|
103 <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> |
102 </ul> |
104 </ul> |
103 |
105 |
104 <h2>Safe code and sustainability</h2> |
106 <h2>Safe code and sustainability</h2> |
105 <ul> |
107 <ul> |
106 <li>correctness, safety and readability is prefered to performance</li> |
108 <li>correctness, safety and readability is prefered to performance</li> |
107 <li>use strong data typing, declare preconditions and possible exceptions</li> |
109 <li>use strong data typing, declare preconditions and possible exceptions</li> |
108 <li>data structures must be known and well documented – don't use undocumented map keys or properties</li> |
110 <li>data structures must be known and well documented – don't use undocumented map keys or properties</li> |
109 <li>code, comments and analysis should be written in the same natural language</li> |
111 <li>code, comments and specification should be written in the same natural language</li> |
110 <li>there should be a dictionary of used terms, so whole team and also users and customers will speak same language</li> |
112 <li>there should be a dictionary of used terms, so whole team and also users and customers will speak same language</li> |
|
113 <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> |
111 </ul> |
114 </ul> |
112 |
115 |
113 <h2>Small code footprint</h2> |
116 <h2>Small code footprint</h2> |
114 <ul> |
117 <ul> |
115 <li>less LOC (resp. complexity) = better</li> |
118 <li>less LOC (resp. complexity) = better</li> |