Git/testssl.sh
1
0
Fork 0
mirror of https://github.com/drwetter/testssl.sh.git synced 2024-11-24 12:01:35 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated Coding Style (markdown)

Dirk Wetter 2019-08-08 18:24:37 +02:00
parent 6f7d756e9c
commit 9fc097b4c5
1 changed files with 47 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
Coding-Style.md

@ -1,60 +1,70 @@
## Coding Style
### This is a short brain dump which is far from being complete
(This is a short brain dump which is not complete)
* PR *
* you make the life of the maintainer easier if it's only **one** patch w/ **one** functional change per PR
* document your PR -- in the comment field and also comment your code. We need to maintain this
### PR
* Global variables
* use them only when necessary
* Please you CAPS
* initialize them
* make use ``readonly`` if possible and indicate variable types (-i stands e.g. for integer)
* if it's going to be a cmd line switch, there has to be also a global ENV variable which can be used without the switch (see e.g. SNEAKY or SSL_NATIVE)
* Please only **one** patch w/ **one** functional change per PR
* Document your PR -- in the comment field and also comment your code. Somebody needs to maintain this, thus it's necessary also to understand in one+ year what your code does.
* local variables (lower case!)
* declare them before usage
* if unclear initialize them
* indicate variable types (-i stands e.g. for integer)
* Test your PR
* Check all changes you did _in different scenarios_
* If it's an additional check confirm that it works with two bad and two good examples (maybe compare results e.g. with SSLlabs)
* Write a unit test (see `~/t/20_baseline_ipv4_http.t` as an example)
* use "speaking variables" and method names but don't overdo it with the length
### Binaries
* do testing before doing a PR!
* Check all changes you did in different scenarios
* if it's an additional check confirm that it works with two bad and two good examples (maybe compare results e.g. with SSLlabs)
* write a unit test (see directory ~/t/ for examples)
* This project is pretty much portable. It runs with a minimal set of well defined binaries across several operating systems. Even the flavor (BSD/GNU) of some binaries are being tested in testssl.sh before executed. Especially with ``sed`` you need to be careful as GNU sed is only 80% compatible with BSD sed (`sed -i`,` \n`, `\t`, etc.).
* don't use backticks anymore, use ``$(..)`` instead
* use ``[[`` instead of ``[`
* the right hand side within ``[[ ]]`` only needed to be quoted if there's a reason
* mind: http://mywiki.wooledge.org/BashPitfalls
* A Mac or BSD user might also have GNU tools installed. Thus please don't query the OS in an if-statement. Rather check whether the binary supports what you are looking for and set global vars (see HAS_* variable).
* use [shellcheck](https://github.com/koalaman/shellcheck) if possible
* don't use additional binaries: testssl.sh runs on more than just your platform
* if you really, really need to use an additional binary
* first clarify with us
* Don't use additional binaries: testssl.sh is portable and runs on almost every platform
* if you really, really need to use an additional binary, first clarify with us
* make sure in the code it's available on the system before calling it
* never use highly system depended binaries (rpm, ipconfig, ..) as it is not portable or requires lot's of efforts to be portable and the code gets ugly.
* Don't use internal checks for features by determining the OS. Rather check whether the binary supports what you are looking for and set global vars (see HAS_* variable).
* Never use highly system depended binaries (rpm, ipconfig, ..) as it is not portable or requires lot's of if-statements and the code gets ugly.
* If it's an openssl feature you want to use and it could be not available for older openssl versions testssl.sh needs to find out whether openssl has that feature. Best do this with openssl itself and not by checking the version as some vendors do backports. See the examples for HAS_SSL2 or proxy option check of openssl in check_proxy().
* If a feature of openssl is not available you need to tell this by using pr_warning*() -- or accordingly with fatal() if a continuation of the program doesn't make sense anymore.
* every operation (string, etc.) which works with bash internal functions: use them whenever possible (replacing tr/sed/awk), see e.g. http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html
* avoid a mix of several external binaries e.g. (sed and grep and tr) if you can achieve the same with a single binary e.g. awk.
* be careful with very advanced bash features. Mac OS X is still using bash version 3 ([http://tldp.org/LDP/abs/html/bashver4.html](differences))
* especially with ``sed`` you need to be careful as GNU sed is only 80% compatible with BSD sed (`sed -i`,` \n`, `\t`, etc.).
### Programming Style
* always use a return value for a function/method
* Global variables (CAPS)
* use them only when necessary
* initialize them
* make use ``readonly`` if possible and indicate variable types (-i stands e.g. for integer)
* if it's going to be a cmd line switch, there has to be also a global ENV variable which can be used without the switch (see e.g. SNEAKY or SSL_NATIVE)
* make use of the short functions / methods (code starts from ``###### helper function definitions``) like
* Local variables (lower case)
* declare them before usage
* if unclear initialize them
* indicate variable types (-i stands e.g. for integer)
* For new functions/methods document the arguments passed and the return code / string.
* Always use a return value for a function/method
* Use "speaking variables" and method names but don't overdo it with the length
* Make use of the short functions / methods (code starts from ``###### helper function definitions``) like
* count_words() / count_lines() / count_ciphers()
* strip_lf() / strip_spaces()
* toupper()
* newline_to_spaces()
* is_number() / is_ipv4addr() / is_ipv6addr()
* ...
### bash
* Don't use backticks anymore, use ``$(..)`` instead
* Use ``[[`` instead of ``[``
* The right hand side within ``[[ ]]`` only needed to be quoted if there's a reason
* Mind: http://mywiki.wooledge.org/BashPitfalls
* Use [shellcheck](https://github.com/koalaman/shellcheck) if possible
* Every operation (string, etc.) which works with bash internal functions: **use them whenever possible** (replacing tr/sed/awk), see e.g. http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html
* Avoid a mix of several external binaries e.g. (sed and grep and tr) if you can achieve the same with bash. Or at least with a single binary e.g. awk.
* Be careful with very advanced bash features. Mac OS X is still using bash version 3.2 ([http://tldp.org/LDP/abs/html/bashver4.html](differences))