Consider not curating a full custom Python code-style guide

[lukpueh]

transferred from in-toto/in-toto#370

--

Description of issue or feature request:

Following coding style guidelines is extremely important especially for the reference implementations we create at the lab. But I've become increasingly reluctant to point contributors to our guideline document, due to the issues outlined below.

Given that curating our own code style guide is a time-consuming task and there are many excellent code guides out there, I wonder if it wouldn't be better to restrict our guide to:

• pointers to PEP 8 and other well-curated code style guides that match our expectations, and
• only document the differences and short-comings we identify in those guides.

E.g. "Do as in PEP 8, but indent with 2 instead of 4 spaces!" (for reasons XYZ ... needs less horizontal space, consistency with existing code don't want a global flag day, ...)

I'd also like to say that I find the Google Python guide really good and it covers most of the principles of our guide in a clearer way, and other things that I find helpful.

Regardless, we should also configure strong linters on all projects (see e.g.
secure-systems-lab/securesystemslib#243) to enforce the code style we expect.

---

Issues with the current guideline

• unclear mix of " and ' (see Single quotes (') or double quotes (") #4)

• Python2-centered, e.g.: use of print statement and file built-in, mention of Python 2.3 (!!) and 2.6, no mention of Python 3

• several inconsistencies between recommendations and examples, especially in the "Maximum line length" section, where the "how it should be done"-example has wrong line continuation indentation, unclear line break condition (neither hanging nor aligned indent, nor breaking close to 80 chars), no blank lines to separate logic, use of format operator which is advised against. Other inconsistencies include recommended but missing underscores in "Naming" section, missing whitespaces around operators in some string concat examples, etc...

• some code examples are unnecessarily comprehensive, so that the emphasis on the specific recommendation suffers (especially in "Maximum line length", or in "Never use short circuit..")

• syntax errors, e.g. assert(x = y), or the incorrectly continued strings in "Never use short circuit.."

• obsolete recommendations about subprocesses (these things are documented in in the Python reference of the subprocess module and only add clutter here) and pointers to archived Seattle code

• important drawbacks in our custom docstring format

  1. not Sphinx-friendly
  2. (less important) needs more vertical space than necessary

  I suggest using Google style docstring, for which there is Sphinx extension, and which needs less vertical space than the similar NumPy style, and which (just as NumPy) is also friendlier to the human eye than the standard reStructuredText Docstring Format.

  See Revise and update source code documentation and build with sphinx in-toto/in-toto#369 for a recent switch to Google style docstring.

[joshuagl]

I'm really supportive of this.

Ideally we would be able to provide potential contributors a linter and editor configuration such that they don't need to think too hard about the coding style (and have the CI take care of verifying it for the maintainers). Currently it's hard for even well-intentioned contributors to meet the coding style because modern editors default to linting with an existing standard, i.e. VSCode enables linting by default with Pylint which follows PEP 8's style guide.

[joshuagl]

Note: the global flag day argument for sticking with 4-space indent is somewhat ameliorated by the --ignore-revs-file/blame.ignoreRevsFile option added in git 2.23. See a discussion on how to do that here: https://www.moxio.com/blog/43/ignoring-bulk-change-commits-with-git-blame

[woodruffw]

• I suggest using Google style docstring, for which there is Sphinx extension, and which needs less vertical space than the similar NumPy style, and which (just as NumPy) is also friendlier to the human eye than the standard reStructuredText Docstring Format.

👍 to this! The Google docstring style is much easier to read when reviewing source, and tools like pdoc support it out of the box.

[JustinCappos]

I'm also supportive of this.

We should take a quick look / poll of other Python projects in the lab to be sure this won't cause a major issue first...

[shibumi]

Is the maximum line length of 79 characters per line set? I think the character limit of 79 is pretty oudated and even Linus Torvalds realized this and they are discussing increasing the limit for the kernel code right now.

Python can get very verbose (especially if you have lots of nesting). This gave me headache, while solving this PR here: in-toto/in-toto#379

The problem was, that we do not from securesystemslib import *, but on the same time we need to satisfy the line limit of 79 characters. This lead to this fix here:

https://github.com/in-toto/in-toto/blob/59058a886cce7e57e8b9660143f5bb81af016eda/in_toto/verifylib.py#L145L147

I needed to manually disable a specific python linter attribute to fix the issue related with the PR.
The linter attribute said:"variable has to follow snake_case", even if it's just a single letter.

[lukpueh]

Is the maximum line length of 79 characters per line set? I think the character limit of 79 is pretty oudated and even Linus Torvalds realized this and they are discussing increasing the limit for the kernel code right now.

I still think 79 is quite reasonable, especially when you only have two spaces per indentation level, as we do. :P It also allows me to have two pages of code side by side on my 13 inch laptop.

Python can get very verbose (especially if you have lots of nesting).

I think the solution here should be to avoid lots of nesting. :)

The problem was, that we do not from securesystemslib import *, but on the same time we need to satisfy the line limit of 79 characters.

Maybe we can use the google style import convention, I mentioned in this comment. This should lead to shorter lines.

[joshuagl]

Maybe we can use the google style import convention, I mentioned in this comment. This should lead to shorter lines.

I like this suggestion. The required changes to module names will doubtless help any downstream's who use our libraries with this style of module import.