27

I've stumbled upon the following request which suggests to include a style guide as part of the HTML documentation.

I can see the purpose of a style guide within a documentation, however these are often opinionated. Sometimes there are more or less official style guides (e.g. PEP8) and I think those should be included/referred, but for most languages there is nothing similar.

What is the general stance towards unofficial style guides?

4
  • We have PSRs in PHP, but they're not really official, rather recommendations from a self-imposed "standards" group… Some people are referencing that style guide. Shall we really keep these references?
    – bwoebi
    Jul 26, 2016 at 15:08
  • 26
    I think styleguides are about as opinionated as something can get, and I think the reason for not allowing opinionated Q/A is a good one and that there should be an effort to avoid opinionated documentation.
    – ivarni
    Jul 26, 2016 at 15:08
  • 2
    Related: meta.stackoverflow.com/questions/328582/…
    – Andy Mod
    Jul 26, 2016 at 15:23
  • 2
    Also related: meta.stackoverflow.com/questions/328528/… Jul 26, 2016 at 16:04

2 Answers 2

3

I just want to add that I'am the one who requested the styleguide for HTML. My thought about this one was not to create a specific styleguide example: "Use 2 spaces for indenting". But rather since HTML for most people is their first language so mention some of the most general things such as "It's concidered good practice to indent nested element" and give an example what it means to indent code.

It would still be some-what opinon based yes. But as a fresh developer it is not sure that you even will understand that a styleguide is opinon based, or why some code you have seen has been indented.

Here is an example of what I had in mind:

Every developer have their own style and styleguide with the goal to make their code easy to read and maintain good readability. When developer work in teams a documented styleguide is normaly used to make sure that the whole team style up their code in the same way.

In a style guide for HTML some of the following might be included:

  • If code should be indented or not, if it should be indented with spaces or tabs
  • etc...
6
  • 7
    Thing is, even when it comes to the question about what should be indented I've seen a lot of different opinions. Some people never indent <head> and <body> to alleviate line lengths in deeper nested tags, some people don't indent the contents of inline <script> blocks for the same reason. Some people indent the contents of <p> tags after a linebreak while some prefer text-content to start right after the tag. For attributes I've seen ever more variety. I'm not sure you'd find a good consensus.
    – ivarni
    Jul 26, 2016 at 17:07
  • Yes, I agree but this is still some-what specific. What I talk about is more something about what a styleguide is, and what -most- (what most is, would be kind of opinon based) developers would take up in their styleguide ex. Indenting, comments. But also to mention that is is up to the developer himself to decide what should be in the styleguide. - So, not to speak about the specific, but more of what a style guide is, and example of what a developer might include in a styleguide.
    – Alex
    Jul 26, 2016 at 17:12
  • 6
    I see what you're getting at, and I'm not opposed to informing people that automatic linters are a thing and maybe throw in som links to those who exist (there's several out there aimed at HTML and templates). I'm still not sure how useful it would be for a total newbie to jump straight into setting up a tool-chain but at least it wouldn't be a potential source of... let's call it heated debate.
    – ivarni
    Jul 26, 2016 at 17:21
  • Four spaces, braces on new lines, double quotes, Google chrome, Linux, ninjas, star wars, batman... 'nuff said
    – user4639281
    Jul 27, 2016 at 2:39
  • 1
    @TinyGiant were are you leaving magic, unicorns and waffles?
    – Braiam
    Jul 27, 2016 at 2:45
  • 1
    @TinyGiant: Four spaces? Braces on new lines? You're a savage!! Jul 27, 2016 at 12:07
1

I just want to chime in with an example of what I consider an official "style" guide: Microsoft's Framework Design Guidelines for .NET on MSDN. Also, consider that the Code Analysis Tool that is included in Visual Studio issues warnings for violations of the Framework Design Guidelines.

That said, I am ambivalent about simply "parroting" these guidelines within SO's new Documentation feature. (This actually reflects my ambivalence about the entirety of Documentation as it now stands.) For such matters, I will always place more trust in the language authority's documentation.

In Q&A, with respect to matters that concern language/framework conventions, I have always appreciated links to the language authority's documentation. Similarly, in Documentation, perhaps such links can provided in the introductory material for the appropriate topics.


Of course, a programmer can always choose to ignore such warnings. But this should be done in a clear-headed fashion.

1
  • 1
    This, plus that Documentation is actually more about examples and not so much about literal documentation. Its not the place where you would put a full-blown guide of any kind.
    – Gimby
    Jul 27, 2016 at 15:11

Not the answer you're looking for? Browse other questions tagged .