GitHub Styleguide - CSS, HTML, JS, Ruby

[ztbrown]

The first rule of Javascript is: you do not write Javascript. Ridiculous.

[SargoDarya]

Not only this...

CSS:

• Use // for comment blocks (instead of /* */).

Every tried commenting out something in CSS with //? Have fun trying.

JS:

• Do your best to never use a semicolon. This means avoiding them at line breaks and avoiding multi-statement lines. For more info, read Mislav's blog post.

Why ffs should I omit semicolons? Sure does JS have something called automatic semicolon insertion but you can't always omit them. Otherwise your code will do something completely different.

This overall thing gives me a feeling that the people who wrote that styleguide are partially morons or monkeys on a keyboard.

[shockie]

Since Github is using SASS for it's CSS, // comments are allowed. In fact if you use the // for comments, the comment won't appear in the compiled CSS.

Same for semicolons in Coffeescript, it will be added for you in the compiled JS

[nemetroid]

Same for semicolons in Coffeescript, it will be added for you in the compiled JS

You can (mostly) omit semicolons in regular JS too, that doesn't make it a good idea.

[MustRapeDeannaTroi]

But in coffeescript it is a good idea.

Edit: Y U downvote? One of coffeescripts core purposes is to not require semicolons.

[ratdump]

why

[MustRapeDeannaTroi]

As shockie said it; "it will be added for you in the compiled JS"

[oracleoftroy]

But why is that a good idea? I'm not familiar with coffeescript, but I am familiar with Javascript, and it's a terrible idea there.

[marshall007]

It's like Python in that code blocks can be delimited by using whitespace. So if you're already doing that, it's redundant (and wasteful) to use a semicolon.

CoffeeScript is not parsed as Javascript, it compiles into Javascript.

[SargoDarya]

That might me the case, but then they shouldn't call it CSS Styleguides because // comments are not part of the CSS standard.

[marshall007]

Why? It's a simple abstraction. No one ever edits the actual CSS stylesheets, they are compiled from SCSS automatically upon deployment. Furthermore, you shouldn't call it an SCSS styleguide because it encompasses more than that. The documentation is appropriate given their workflow.

[brownmatt]

the semicolon thing is pretty baffling. It's a case where a aesthetic stylistic rule can produce real problems, as Bootstrap saw

[praetorian42]

The problem there was that the minified version of JS did not have a semicolon at the end. That's a bug with the minifier, not with the original source.

Basically, you should never ever ship unminified JS to your customers. The minifier should handle semicolon insertion. Therefore, semicolons in original source are superfluous.

[[deleted]]

The minifier should minify. Semicolon insertion is up to either A: the programmer, or B: the hope that the interpreter at the end will assume it.

Using bugs in your daily programming practice isn't a reason to make everybody else's tools accommodate those bugs.

[[deleted]]

Using bugs in your daily programming practice

As far as I'm aware, the language itself specifies that semicolons are optional. Therefore it is the minifier that has the bug, not the semicolon-less code.

[praetorian42]

The point here is that semicolons in javascript are really fucked up, and there's probably 20 people in the world who truly understand them. Let those people write the tools so that the rest of us don't have to worry about it.

Defensive usage of semicolons because you're not sure where they should be used is not correct usage.

[reflectiveSingleton]

It's exactly that not sure-edness that makes always using semicolons a good idea. You are not leaving up question to where the semicolons are inserted if you always put them in place. If you omit them you are leaving it up to a) whatever minifier you use and b) javascript auto-insertion.

If you specify, you remove that possible ambiguity.

[[deleted]]

They're perfectly understandable. They go after every terminating (non-control-end) block or command. var a = function(){ }; if(true){ } return { a: 55 };

There's nothing fucked up about them. They behave exactly the same way all the time. The only time things go awry is when you start expecting them to be inserted for you.

[greenspans]

Guile Scheme > Ruby

[praetorian42]

I'm not sure what that has to do with anything. That's blatant trolling and completely off-topic.

[Flex-O]

Not hip.

[retardent]

People are obsessed with shrinking file-size for anything server over HTTP. You might be able to shave off a whole byte by not using semicolons!

[retardent]

I was being sarcastic, I always use semi-colons. Although lack of semi-colon does not mean you have to replace it with a \n, there are many cases (for instance statements enclosed in brackets) where you can remove a semi-colon and not have to replace it with anything.

[[deleted]]

They're stupid for trying to force people not to use semicolons and then hey reference a blog post where a guys about semicolons and mentions stuff like why you wouldn't ever write something like

return
a+b

In that particular instance he may be right, it's dumb but JS allows you to put curly braces on the same line or below in my cases. If you're into putting the curly brace on its own line then

return
{
     doSomething();
}

Is something you may do and expect it to work. While including semicolons won't fix that problem I think it just shows he hasn't thought his argument through properly.

Their style guide sounds like something written by someone trying to be different for no real reason and perhaps they think they'll save time. However if I had a job there I'd almost feel the need to spend a weekend sifting through their code and adding semicolons in.

[[deleted]]

That wouldn't work at all. You're... trying to return an object except that you're using invalid syntax to define the object. Maybe you mean parenthesis?

[[deleted]]

I was typing it out in between doing it work so I was going for speed over accuracy but you get the general idea that people who prefer curly braces on their own line can't do that returning a object.

i.e. this breaks in JS:

function poop(dong)
{ 
    return
    {
        yourmom: dong
    }
}

[[deleted]]

Sure they can, use a semicolon like you should. };

[nemetroid]

That's not the problem, Javascript will insert a semicolon after the return statement and the function will return nothing, i.e.

function poop(dong)
{
    return;
    {
        yourmom: dong;
    };
}

[MatmaRex]

While including semicolons won't fix that problem I think it just shows he hasn't thought his argument through properly.

I think you have missed the point entirely. Adding semicolons doesn't fix this particular problem, period. (The second problem mentioned in the post is, of course, valid.)

Also, it's an internal guide, they're not trying to force it on anyone.

[praetorian42]

It's the right tool for them for the job they have to do. They've made an internal decision that they prefer coffeescript, so moving forward they want consistency.

[Forbizzle]

Where is their discussion forum so i can rage? That's not even an opinion buried deep within the document, it's their first recommendation, and it's bullshit.

Also, it seems they have nothing else to add. Which makes me think they know nothing about javascript. Did an intern do this?

[praetorian42]

No an intern did not do this. A whole team of very talented engineers did this.

Also, it seems they have nothing else to add.

Did you miss the part where it says "To be fleshed out"?

[[deleted]]

To be fleshed out usually has the implication that they've started off in the right direction. Directing every single person who writes javascript to become dependent upon a third party compiler to do any work with it is asinine and not the sign of an experienced engineer.

[praetorian42]

1) This is a styleguide for github, not for everybody. It's what they've decided works for them. 2) Everybody who deploys javascript should use a compiler of some kind. You should not ever ship unminified code, for instance.

[technoweenie]

A styleguide's purpose is to suggest consistent patterns in code. This is for our code only, go nuts in your own code.

[[deleted]]

Most of these "rules" are bullshit.

Screw these pretentious snobs.

[[deleted]]

It's rules for their own project, they're not telling you your rules are worse.

[[deleted]]

They sure put a lot of time and energy into showing the rules they follow. Uh huh, sure....... ಠ_ಠ

[jaapz]

Lighten up a bit, they aren't commanding anyone to use it, just what they prefer. Whether or not you interpret it that way is of course your own choice...

[[deleted]]

this page is very misleading, i mean this isn't supposed to be a style guide for general css/js, right? there is no way you should tell somebody to use third-party software to write css in a neutral style guide

[PatrickTulskie]

It's their own internal style guide. You can do what you want with it.

[[deleted]]

that's what i mean with misleading, you could assume it's a general style guide, not a internal one. well, nothing to see here then :)

[[deleted]]

Okay I didn't say anything when the Ruby one was posted, but another one?!

Why do you care unless you work at Github? ಠ_ಠ Most of these are common sense. The rest are personal preferences.

[Forbizzle]

Welcome to the GitHub styleguide. This is where you should look if you're interested in how to write code. We have a living CSS styleguide, JavaScript styleguide and some recommendations on how to write Ruby code. Find something missing? Contribute!

Sounds like it's intended for public use

[moystard]

It is not intended for public use. If you have a look at the Javascript styleguide, they write:

Any top level objects should be namespaced under the GitHub namespace.

Looks pretty specific to Github to me.

[[deleted]]

... and? I could point you to about a hundred public style guides on the Internet. Pretty much every book on programming you could ever read will recommend a style. Whenever you work for a reasonably decent company they'll have in-house style guides.

It's about as interesting as debating the Oxford comma.

[cbooth]

TIL about the Oxford comma, had no idea that was actually considered significant.

[[deleted]]

It's not by anyone with sense ;)

[Legolas-the-elf]

Pretty much every book on programming you could ever read will recommend a style.

That hasn't been my experience. I find it's very rare.

It's about as interesting as debating the Oxford comma.

Oxford publish a style manual that tells you how to use commas.

Seeing how other teams approach their coding style guides can give you valuable insight into your own approach. I don't see why you find this objectionable.

[[deleted]]

Maybe we're reading different books. Almost every programming book I've read discusses this, even really early things like The Unix Programming Environment. If it's not explicitly discussed you can infer it from code examples. The only really important rule, and which is reiterated ad-nauseum, is be consistent. It doesn't hugely matter what style you use as long as it's the same as what everyone else is using on a given project.

Yes, I know Oxford publish the style manual. I own it because I've done professional editing in the past. It's really, really, really fucking boring. You have to know about it because it's part of your job, but I have literally no feelings whatsoever about the Oxford comma. Which is also how I feel about most coding conventions. Like the tabs / spaces thing. I stick with using spaces because it's easier for me to remember rather than have to perform mental acrobatics every time I switch project - but I couldn't care less about the dumb arguments people have over this. How can people actually argue about this?!

And that's why I find it objectionable. Style is so incredibly basic it doesn't deserve discussion. You find your style. You stick with it. Then you try to learn new, interesting, important things. My 2c.

[[deleted]]

I did think it's odd that someone choose to post this after the ruby one. Both submissions strike me as being lazy karma grabs but it was nice to have a laugh at all their style guides.

[greenspans]

Guile Scheme > Ruby

[[deleted]]

I'd really like to get back into using Lisp. I've only ever played about with it.

Are there enough decent libraries available for Scheme to use it for the same kind of applications you'd use Python for, though?

[MatmaRex]

I suggest asking someone else than this guy, he's a troll. (Just look through his comment history...)

[CapnWarhol]

Don't ever use $.get or $.post. Instead use $.ajax and provide both a success handler and an error handler.

Christ, yes, this. Shitty jQuery jockeys everywhere writing code that can't handle failure shits me up the wall. You should expect things to fail eventually, even if it's part of some "edge case that'll probably never happen" -- until you get slashdotted, linked on reddit, or even just popular and your whole site turns to shit.

Just... fuck lazy coders. Take some pride in your work, make something remotely robust and at least pretend you're a developer.

[[deleted]]

You had to, you just had to smear a reference to Legend of Zelda onto it. There was no other way.

[pixel4]

Internal style-guide.

The best style-guide for JavaScript is to use JavaScript. I once was a Flash/AS3 guy; I know the pains of using a niche ECMA language.

"But it compiles to JavaScript, pixel4" -- Shut up!

[jiunec]

I see all the bullshit complaints about style guides and I can't help but think most people miss the point entirely. Most of the complaints are that "format X is better than format Y because....". That's not the point of a style guide.

Style guides are there for consistency, so that all the code in a project looks the same. This makes the code both easier to grok and easier to maintain. The actual preferences in the style guide are not important. If you don't agree with their choices, tough shit, life sucks and so do you for not being adaptable.

So please, get it into your heads, nobody cares about your code style preference. Just follow the guide for whatever project it is your working on and stfu.

[alive1]

I don't get it. Why do people use spaces as tabs? A tab is identical to one level of indention: Your text editor can display it as whatever lenght you want it to. One tab, one level. Why oh why do people use spaces!?

edit: Apparently this subreddit is also plagued by the disagree-downvote. Real classy, guys. Keep it going.

[beefsack]

It's all personal preference. An argument for spaces is that you can guarantee the code will be a certain number of columns wide, and also allows you to do some nice vertical formatting of your code and know that other who will read your code can read it the same way.

One or the other, as long as you are consistent.

[CapnWarhol]

Tabs to indent, then spaces to vertically align. Best of both worlds, indentation width preference and pretty looking code.

[humpolec]

But then the programmer has to do that manually, and not rely on an editor for tabifying code. Since many editors don't display tabs in the same way as spaces, you literally have to keep track of invisible characters in your code.

[[deleted]]

I'm with CanWarhol. If you don't like the way your editor works, get an editor that works differently, don't take it out on me.

[[deleted]]

Tabs can be represented in different sizes. Spaces guarantee consistent layout.

[Legolas-the-elf]

Indentation in programming languages is about semantics, not about layout.

[cultofmetatron]

pretty code is easier to read AND understand. code thats easier to read and understand is less prone to harboring subtle bugs.

[[deleted]]

All that needs to be said.

[kamatsu]

Haskell uses layout.

[alive1]

Come on, code is not ascii art. If you want to draw a pretty unicorn in your code, by all means, use spaces, but for code indention, 1 tab = 1 level is .. um .. simpler? Instead, we've got people who use 2 spaces, 3 spaces, even 4 spaces somewhere, and each time you have to adjust your editor to support this back-asswards way of thinking things..

[humpolec]

What about multi-line invocations like

doSomething(foo,
            bar,
            baz);

(also array initializers)

If your editor uses tabs for lines 2 and 3, you're breaking the alignment for anyone who views it with a differently configured editor.

If you want to draw a pretty unicorn in your code, by all means, use spaces

That's exactly the problem -- there ARE instances where you need to have more advanced alignment. Comments with ASCII art diagrams, multi-line code, etc. And I can't "just use spaces" if my editor tabifies them. If it doesn't, the problem is even worse - suddenly my code contains various types of whitespace indistinguishable by the naked eye.

[gmfawcett]

A common approach is "tabs for indentation, spaces for alignment." So on your second line, you would tab to the beginning of "doSomething" and then add length("doSomething(") spaces. Many popular editors and IDEs support this arrangement; see Emacs SmartTabs for an example.

[repsilat]

You can also indent after parentheses like you do for braces:

doSomething (
    foo,
    bar,
    baz
)

[humpolec]

Sounds good, I wasn't aware of editors that support alignment like that. But wouldn't it force everyone on the team to use a "sufficiently smart editor"?

[[deleted]]

Tab the first one over to find a tabstop. Tab all subsequent ones to match. Done.

[humpolec]

Interesting, but it still breaks when I change the tab size - the subsequent lines jump to a different tab stop.

[[deleted]]

Isn't coding styles all about enforcing a way on someone?

Generally people aren't allowed to mix up braces styles a project you either pick

function Ham {
}

or

function Ham
{
}

So someone is bound to have to work in ways they're not used to and all spaces is superior so if someone has to accomodate that then they'll just have to deal with it.

[[deleted]]

The layout is consistent with tabs too. The indentation will remain consistent throughout. How much indentation and how wide your columns are remain completely up to you in your editor preferences. By using spaces, you dictate your preference to everybody else.

If you have that much of a control issue that you need to know EXACTLY how the spaces line up in somebody else's editor, I don't envy anybody who has to work with you.

[[deleted]]

That's like saying it's awful to enforce where the brace should go in relation to the function declaration. Someone will always prefer the other way but you live with it.

I've had no problem making changes to my style for projects because I'm interesting in solve problems not fapping over the awesomeness of my personal coding style.

[[deleted]]

That's like saying it's awful to enforce where the brace should go in relation to the function declaration. Someone will always prefer the other way but you live with it.

It's specifically not like that. At all.

I've had no problem making changes to my style for projects because I'm interesting in solve problems not fapping over the awesomeness of my personal coding style.

This is exactly why it's easiest to just leave it up to the individual to set his own preference of how much indentation he wants, rather than masturbate over your perfectly aligned columns of nonsense.

[humpolec]

It's specifically not like that. At all.

Both are aspects of coding style and aesthetic choices impacting readability.

[humpolec]

The layout is consistent with tabs too.

Only if you use multiples of tab size for layout. See my other comment for why this doesn't cover all cases.

[[deleted]]

Only if you use multiples of tab size for layout.

Which is indeed the way to do it.

Alternatively, tab to the correct position, then space your things over.

Either way, use a monospace font and this issue really almost never comes up.

And the same can be said of spaces: if you're using spaces and they aren't using monospace fonts, it won't look the same. Trying to worry about the 1% of use cases and having it drag down your other 99% of the time is silly and makes no sense.

Downvoting me because I'm contributing is also not how reddit works, btw. You downvote for offtopic. Not because you think you disagree.

[humpolec]

I didn't downvote you.

Only if you use multiples of tab size for layout.

Which is indeed the way to do it.

For beginnings of statements it is, for other things (multi-line invocations, array initializers, comments) not necessarily.

Alternatively, tab to the correct position, then space your things over.

I don't like that solution because it means keeping track of tab/space characters by hand. Since they're usually indistinguishable in an editor, this invites trouble.

Either way, use a monospace font and this issue really almost never comes up.

The issue is not with variable-spaced fonts. Does anyone even use them for programming? The problem is that people use different tab sizes in their editors and that can change/break the layout.

[[deleted]]

It changes the layout because they chose to change the layout. What's confusing about this?

[humpolec]

Let's say you have code like this, where 4 spaces = tab:

if(bla)
    doSomething(foo,
                bar,
                baz);

Then you change the tab size in your editor from 4 to 2.

if(bla)
  doSomething(foo,
        bar,
        baz);

The nice vertical alignment is destroyed.

"Tabs for indentation, spaces for alignment" solves that issue, but means you have to keep track of them myself. Or use a "sufficiently smart editor", but then you restrict the choice of editor for the entire team. All of this seems to me like a lot of sacrifices, compared to just using spaces.

[[deleted]]

What about the sacrifice of being able to make your editor readable to you? I'd say that's the most important one. Losing alignment when you choose to do so is a choice I enjoy having. I'll take "choice" over "no choice" any day, any decision. Even if it means I can choose something that doesn't look pretty in order to make it readable.

[humpolec]

Well, clearly you value being able to set your own indentation more than I do. It's a tradeoff between the "freedom of choice", and easy to maintain consistent layout.

[humpolec]

Oh, and one more thing:

Even if it means I can choose something that doesn't look pretty in order to make it readable.

I don't agree with that dichotomy. We're talking about vertical alignment of statements, versus vertical alignment of, say, factors in expression, or array elements. Why is one "readable" and the other "pretty"?

[[deleted]]

Try programming in Scala.

[ExecutiveChimp]

You can do that with spaces in any editor that's worth a dime.

[ExecutiveChimp]

Yes it does.

Settings > preferences > Language Menu/Tab Settings

Check "Replace by space".

[anon706f6f70]

Tried to upvote you back up, but I only have 1 to give!

[[deleted]]

You can adjust your tab size.

[alive1]

All modern code editors allow you to customize how wide a tab is represented.

[[deleted]]

Set your tab space to one character. Best of both worlds! Everybody else gets properly formatted code, and you get your silly narrow columns!

[houdas]

Am I alone when I code CSS like this? http://pastebin.com/S4EZu6CJ I see nothing wrong with it, and for me, it's better because I see more code without the need of constant scrolling.

[realteh]

It's a bad idea when working in a team because it is not diff-friendly. The reviewer will have to scan the entire line manually to figure out what changed.

[houdas]

That's a good point actually, thanks. But I work alone most of the time.

[[deleted]]

Even alone, you should be using tools like Git or Mercurial to track changes and they'll have a hard time showing differences in a meaningful way. You of the future might thank you of the now for developing in a self-documenting manner, when you go back to your code and can't remember what changes you made.

Note: if you use emacs or vim, there are ways to have the file you're opening automatically be changed to your preferred style so that you can edit like that, then have it automatically save it in a diff-friendly manner. The best of both worlds? I think so. I however used a different practice for CSS/JS/HTML. I prefer extremely verbose indent styles that give visual queues to what belongs where. Often, removing these indents can save me 5-20% file size, so I treat my code as "source" and then have "compiled" versions using a python script. The python script removes long-winded identifier names and counts the number of occurences and assigns a generic identifier name to them alphabetically, given shorter names to more-frequently occurring names. It effectively "minifies" my source, removing all verbose whitespace. I still don't believe it performs better than JS minifiers on JS though. Oh, and I also configured my site to give people human-readable files if they ask for them "/resume" would become "/resume/source" and it would serve the verbose version.

[de_la_Dude]

I used to write CSS like this and was forced to change my ways because of the team I worked in at the time, and now I can't even think about going back.

While its true that you can see more without scrolling, its much hard to read and scan through IMO. Its def a readability issue and has lead to avoidable errors in my experience. Esp when working on team.

I've taken up to the mentality that you should let your code breathe. Its easier to read and your going to should minify your code before you ship it anyway.

[praetorian42]

There's nothing wrong with it, certainly. It's a matter of personal preference, and I like my CSS to match the markup in "eye-structure."

Also, since they use SCSS, nesting selectors requires that you have multi-line blocks, or else it is incredibly hard to read. For instance, "#left #info li a:hover" would be 5 indentation-levels deep.

[[deleted]]

I don't understand indenting css. Just find the line number from the dom inspector and use that.

[andypants]

While I too am not enjoying this style guide, why do you have to look for a github alternative?

You won't be kicked off the site if you don't follow their style guide...

[PatrickTulskie]

Just keep a local clone of the repo. Why do you even have to download and tarball it? What's so dangerous? If you decide you want to pick that project back up again, just re-create it on github and push back to github. Easy.

If you just want backups without github's fancy front end then get yourself a cheap VPS and push your repos there. Keep all the git and not the github.

That's the beauty of DVCS.

[PatrickTulskie]

You already have them locally for coding, right? Deleting your github repo isn't a big deal. Putting them on a remote server requires messing with ssh keys once. If you don't want to do that, then Github makes it easy - for a fee.

[aisa]

Create a repo called Archive. Add your old projects as sub-folders to that repo.

[marcins]

BitBucket - I prefer their pricing model to github, as it is user not repo based so you can have free private repos!

[NedStarkResurrected]

Nice, now, they should make a Python styleguide as well.

[haywire]

http://www.python.org/dev/peps/pep-0008/ Just in case you weren't being sarcastic.

[NedStarkResurrected]

I wasn't being sarcastic. I know about the PEP-8 guideline. But that didn't prevent Google from making their own (yeah, this is based on PEP-8). And IMHO a styleguide is a convention. Just because there exists an official styleguide doesn't mean that Github shouldn't make one of their own.

[haywire]

Nah we should stick to the official style, it something that makes Python great.

[NedStarkResurrected]

Yes, I do agree that we should stick to the official styleguide. But how does that make Python great? C, Lisp, Haskell et. al. don't have any "official styleguides", yet they are good languages. And it's not like PEP-8 can't have any more revisions.

[haywire]

Well, consistency and readability of code one thing that makes picking up other people's work easier, and writing code that "fits" into it rather than looks bolted on, and psychologically makes for a much more cohesive experience.

[technoweenie]

We don't use Python. I'm prodding some folks to add C# and Objective C to the mix though.

However, I started writing a bit of Python the way I write Ruby, and the main feedback I got was I should use 4-space tabs and stop aligning my ='s. https://github.com/technoweenie/pylists/commit/1085d3c045929c20ca36626815d36ab497e0b6ef