0

When I read coding style guides, such as the AirBnB Javascript Style Guide I just realized that these often do not provide deeper explanations why something should be done in a particular way.

At most there are brief statements, rarely links e.g. "It won't work in IE8. More info."

Why is that that so? At least a list of references or a link to an annotated version would be more helpful, e.g. to new employees that must work with such a style guide.

Are there notable counterexamples, for any language? (Cannot read them all)

I'd consider these style guides as "living documents", and over time I would expect them to grow into more verbose versions with many links, conserving lessons learned and documenting how to avoid obscure edge-cases.

It's okay to start with a bare-bones document. That's easier to read. but shouldn't evolve these documents, a longer version indicating a more "mature" style-guide?

|improve this question
  • 3
    Because either 1) the reason is obvious to everyone who knows the language well, or 2) there is no reason because all the options are fine but you want to pick one for consistency's sake, or 3) the style guide might suck. – Ixrec Nov 14 '15 at 19:49
  • I consider the JSF C++ Coding standard to be a counter example. – Bart van Ingen Schenau Nov 15 '15 at 8:00
2

First, a style guide is neither a tutorial, nor a text book for learning best practices. If you want comprehensive explanations, you need to read a book like "Code Complete", or something of similar size. But that is nothing you read in one or two hours.

Moreover, lots of details in style guides are opinionated, and some rules are just there to impose consistency within a team. There is often nothing like a "deeper explanation", sometimes its just "the majority of our devs voted for function names starting with upper case letters, that's why we picked this style".

|improve this answer
  • "the majority of our devs voted for function names starting with upper case letters, that's why we picked this style" - good enough rationale for my taste. It's nice to see when there's some actual "physical" reason vs majority voting behind some decision. – scriptin Nov 14 '15 at 20:03
1

Where I work, the used/defined code style guides were the result (essence) of former discussions among developers. Usually nobody is interested in reproducing longer discussions, but interested in documenting their outcome. Typically those guidelines are intended for the new staff. Usually you do not create a new styleguide, when you hired a new team member - since discussions are time consuming - and do not lead that much into new insights.

If you need an in depth knowledge why a particular rule is created/used you must ask the writers themselves or I fear you must research this for yourself why a particular rule was created.

|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.