Code Style Guide

[sfrisk]

We need this specifically for HTML and CSS, although we already have a CSS style guide (http://contribute.jquery.org/style-guide/css/), and a limited HTML style guide (http://contribute.jquery.org/style-guide/html/) posted on the jQuery website. Are there additional/different style guide guide standards we'll want to enforce?

I'm particularly thinking we might want to flesh out the HTML style guide a bit more than what we currently have. Perhaps create a SCSS style guide, since that seems to be what we'll be using for CSS?

[arschmitz]

I think we will probably just add to the css style guide once we decide on rules for scss. I agree the html style guide could use some work.

[sfrisk]

I have the HTML style guide on my list of things to work on this week/weekend - so if there is anything people know they want to see in the html style guide that is not currently in there, let me know, and I'll create an issue for it in jquery/contribute.jquery.org

[sfrisk]

Related to: https://github.com/jquery/contribute.jquery.org/issues/92

[cbracco]

How do you guys feel about using a linting tool and/or CSSComb to further enforce code styles?

[arschmitz]

@cbracco id say we are in favor on the jQuery side we have this style guide @sfrisk just finished first item is our css lint rules http://contribute.jquery.org/style-guide/css/ I have not looked at cssComb ill check it out.

[sfrisk]

Definitely! We already use CSSLint for other jQuery projects http://contribute.jquery.org/style-guide/css/#linting

[sfrisk]

... oh guess you got to it first, @arschmitz

[arschmitz]

:-p

[cbracco]

I whipped up a CSS code style guide not too long ago, just posting it here for reference in case there is anything we would like to use from it!

https://github.com/cbracco/css-conventions

[cbracco]

We can also include an .editorconfig file to set some sensible tab / spacing defaults for various file types.

http://editorconfig.org/

[jzaefferer]

I'm not sure how the CSSComb integration would look like, since it seems to output code, not just lint it. It also depends on #17. Anyway, here's a potential CSSComb config, created using their generator, which should reflect what's currently in the CSS style guide:

{
    "remove-empty-rulesets": true,
    "always-semicolon": true,
    "color-case": "lower",
    "block-indent": "\t",
    "color-shorthand": true,
    "element-case": "lower",
    "eof-newline": true,
    "leading-zero": false,
    "quotes": "double",
    "space-before-colon": " ",
    "space-after-colon": " ",
    "space-before-combinator": " ",
    "space-after-combinator": " ",
    "space-between-declarations": "\n",
    "space-before-opening-brace": " ",
    "space-after-opening-brace": "\n",
    "space-after-selector-delimiter": "\n",
    "space-before-selector-delimiter": "",
    "space-before-closing-brace": "\n",
    "strip-spaces": true,
    "unitless-zero": true
}

Regarding .editorconfig, we should be able to just copy one from another project, like the one from jQuery UI: https://github.com/jquery/jquery-ui/blob/master/.editorconfig

While at it, add .gitattributes, like this one: https://github.com/jquery/jquery-ui/blob/master/.gitattributes

[cbracco]

These all look good to me!

[arschmitz]

+1 for the .gitattributes and .editorconfig css comb looks good to but as @jzaefferer this would be dependent on a build process

[kborchers]

I just came across this and thought it was worth a read and might be useful http://cssguidelin.es/

[cvrebert]

FWIW: http://codeguide.co

[sfrisk]

@cvrebert We'll be discussing this in the meeting today along with #1 at 1pm EST in the #jquery-meeting channel on freenode. Since I noticed you have commented in both issues, I would encourage you to join this meeting or any of our other weekly meetings for the css framework.

[MichaelArestad]

@sfrisk I missed the meeting. Any updates on this?

[sfrisk]

@MichaelArestad We didn't get to this yesterday at the meeting. My goal is do have a new draft of the html one done before the next meeting (6th of January). We still need a SCSS one, especially now that we've made some decisions on naming conventions in #4.

[kristoferjoseph]

This seems like a pretty in depth code guide for SASS: http://sass-guidelin.es/ *yes It is from hacker news.

[MichaelArestad]

Yep. It's pretty good. Hugo did pretty solid work.

[sfrisk]

I saw that on Twitter! Started reading it, it's pretty good.

[battaglr]

Good thing to have a style guide –I don't now how to call them anymore, maybe guidelines– from the start, and I would like help creating them.

I often see that style guides deal with —as I understand— two very different matters:

• Syntax and formatting (the so called style).
• Recommended or established practices.

This is the case of the jQuery CSS Style Guide and the jQuery HTML Style Guide. My suggestion is to document both (formatting and practices), but not mixed up —not necessarily on different files/documents—, since the two are independent and should remain that way –Harry Roberts is doing something very similar in his CSS Guidelines.

I'll try to make my point:

Formatting

This takes care of things like: insert a space between the selector and the curly brace, and so on.

Fortunately we have great tools to help us with that, and we are already using them: EditorConfig, CSScomb, etc.

The thing with syntax and formatting is that (a) they had nothing or little to do with recommended practices, (b) once defined they tend to remain the same, and put them together with recommended practices could lead to really big documents that are not that easy to dive in, (c) are one of the most subjective things and tied to personal taste that I can think of.

To have a real vision of what I'm talking about or if I'm failing to be clear, you can check my CSS Codin’ Style, HTML Codin’ Style and Markdown Codin’ Style. Those documents only define style and formatting rules.

Recommended or established practices

This takes care of things like: never use IDs in the CSS, avoid descendant or child selectors more than three levels deep, and so on.

This recommendations (a) tend to change more often —or should—, (b) may need further clarification, since saying never use IDs in the CSS is very different from insert a space between the selector and the curly brace, because you can argue about an objective recommendation but not so much about a subjective style preference.

What do you guys think?

[sfrisk]

We've had some in depth discussion involving style guides in this and other issues (#11 - although in this case it was more of a pattern library, than established practices/formatting style guide)

As mentioned, we're already using CSSLint to help enforce many of the formatting rules that we have in place, and right now it's helpful to have one page to find all of our formatting/established practices on not multiple.

That being said, we're still reworking the HTML style guide to line up closer to what you see in the current CSS style guide. We also need to start work on a SCSS style guide, if you think that's something you would be interested in working on. I've created a separate issue for it in issue #41

[battaglr]

@sfrisk: great! I may have explained myself wrong, since I don't necessarily suggested separating the two into different documents —and don't really have a preference about that. I just was trying to make the point that IMHO not mixing them up (for example in the same section title) could be a good idea.

And regarding #41: yes, I'll be glad to help with that! :)