As we’re getting larger I was finding myself sharing some tips repeatedly (and leaving some others unexpressed), so I decided to start up a document.
https://github.com/ansible/ansible/blob/devel/CODING_GUIDELINES.md
Could probably use a little bit of reorg and standardization, but this is a draft.
My only point of contention is on lining up variable assignments.
Sooner or later someone comes along with a longer name.
At that point, you either realign existing assignments (ruining attribution) or have a misaligned assignment.
See https://github.com/ansible/ansible/pull/5389/files for a particularly degenerate example.
In general though, this is a great combination of pragmatic and idiomatic guidelines.
Will
This happens but readability is increased.
An imperfect world, but it will not be enforced anyway.
– Michael
*PEP8 please!*
Coding style is mostly a personal preference. The open source code,
however, is being read (and edited) by many people. Note, however, that
there are many personal preferences. And so, we create coding guidelines
etc. to achieve consistency, because it matters!
Now, I said "mostly", because, I believe, some guidelines are dictated
by technical difficulties, say (possibly arguably) screen resolution etc...
People that contributed to PEP8, have had hard time deciding on their
guidelines. Some of the rules, I believe, were dictated by technical
constraints. But mostly for the same reason as above, i.e. personal
taste, in whole it was not an easy decision, and so it took ages. Then
there were some modifications later on, in order to keep up with the
changing world. However, they reached a consensus.
Now, imagine everyone tried to stick to the rules. Not everyone will be
happy about decisions made, but everyone will be able to read, as easily
as possible, because of the *consistency*.
In my opinion project specific guidelines make sense if and only if you
stick to the PEP8, and introduce only those rules that either
* Are already not specified in PEP8,
* or, if you have to, are not precisely specified by PEP8 (when it
gives multiple options).
* Are really necessary because of specific project requirements
that would be hard to maintain while sticking to the PEP8 rules.
If so define clearly the rule and give all reasons behind it.
That being said, "buy a bigger monitor" is not an excuse.
Even if main developers have some prejudice style of coding, it is an
OpenSource project. Ansible is a kind of software that is being used by
different people. Most of us, I claim, meet different coding guidelines
every day, in every project. Why create new standards and make our life
harder? I think we would benefit not simply from local standardization,
but standardization of the recognised rules.
This is not up for debate.
Ouch