Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Replace styleguide with Google guide supplement
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