Skip to content

Commit

Permalink
Replace styleguide with Google guide supplement
Browse files Browse the repository at this point in the history
As discussed in #20 Secure Systems Lab does not need to maintain a
custom Python Style Guide, given the availability of public style
guides that too are based on PEP 8, but are more comprehensive and
generally better curated.

This commit replaces the existing guidelines with a pointer to the
Google Python Style Guide, which seems a good fit for us, and makes
a few refinements, additions and accentuations.

This commit also moves the Python specific recommendations to a
separate document, so that the README can be used as landing page
for other guidelines in the future. Only the preamble of the README
is kept and updated.

Most of the rules and recommendations from the old guide are
covered in the new guide in a similar fashion. However, some items
were changed or completely removed for below reasons.

**List of changes/removals**

- 'Nesting' is moved to 'Recommendations->Miscellaneous' and
slightly updated to mention the "return early" pattern, which is
what it is, and the "arrowhead anti-pattern", which is what it can
help to avoid.

- 'Docstrings and comments' are covered in detail in the Google
guide and refined in the new document, suggesting a more
Sphinx-friendly docstring format and preserving some
recommendations from the old guide.

- Some recommendations about comments are removed, including
"comments should document changes" (commit messages seem better
suited), "write comment as a question" (seems a matter of taste)
and "document your assumption" (seems like an excuse to not test
you assumption, at least in the example).

- "string formatting" is updated to recommend new style `format()`
or newer style f-string syntax and mention pitfalls about string
concatenation

- The example in "Use else statements for handling errors, not for
normal flow in most cases" conflicts with the "return early"
recommendation (see above)

- "Unix not Windows style text files" seems obsolete

- "Avoid objects" and no "No lambda functions or lisp-esque code"
seems too strict as a general rule. Similar more nuanced advice can
be found in the Google guide, i.e. to avoid power features and that
comprehensions, generator expressions and lamdba functions are okay
for simple cases and one-liners.

- The example in "Never use short circuit evaluation to produce
output" is very confusing

- Recommendations about 'os.popen', 'os.system',
'subprocess.Popen', are covered in the Python standard library
reference

- "Avoid changing directory" seems like a corner case

Signed-off-by: Lukas Puehringer <[email protected]>
  • Loading branch information
lukpueh committed Nov 17, 2020
1 parent 532c834 commit 49b4aa8
Show file tree
Hide file tree
Showing 2 changed files with 231 additions and 1,100 deletions.
Loading

0 comments on commit 49b4aa8

Please sign in to comment.