
The GitHub Styleguide - jamesjyu
https://github.com/styleguide
======
mapgrep
I liked their guideline on when to use bang methods like `array.map!` in ruby:

"The names of potentially 'dangerous' methods (i.e. methods that modify self
or the arguments, exit!, etc.) should end with an exclamation mark. _Bang
methods should only exist if a non-bang method exists._ "

That last sentence finally made me understand why `string.gsub!` takes a bang
but `FileUtils.rm_rf(dir)` does not, even though the latter is far more
dangerous (in the generic case). It's not just about the danger level of the
method but about the existence of a non-dangerous alternative. Now I've
started noticing that some gems do not follow this guideline.

~~~
mattbriggs
first time i heard that was from greg browns Ruby Best Practices book (was
probably the best thing I took away from it). At this point (unfortunately)
bang means almost nothing, since the reason to use bang seems to be different
for every rubyist

~~~
gioele
Examples of different uses?

The only example I know of is DataMapper that uses bang methods such as
`save!` for the methods that change data bypassing the validation mechanism.
But I would argue that this use fits the original definition quite nicely.

------
talleyrand
No semicolons in javascript! This is subversive and should be suppressed.

~~~
stephen_mcd
Their justification attributes a blog post where the author basically says
"don't use tools that will break your code if you omit these syntax features".
It encourages people to write code that will break when used by others,
dictating the tools they can and can't use. It's the equivalent of a child
closing their eyes and sticking their fingers in their ears to magically whisk
away the person standing next to them.

It's pretty disappointing to see GitHub, a company that a lot of developers
(including myself) look up to and will follow, espousing something like this.

~~~
MatthewPhillips
They actually don't provide a justification. That blog makes the argument that
omitting them is harmless. Neither GitHub nor the blog make an argument for
why you _should_ omit them, however.

~~~
rtomayko
Do you use semicolons in Ruby, Python, shell, or other semicolon-less language
where semicolons are allowed? If not, what's your justification for omitting
them?

~~~
technomancy
The justification is to be idiomatic and match the bulk of existing code.

------
jedschmidt
Here's a more accurate tl;dr of their JavaScript style guide:

    
    
        $ curl -I https://github.com/styleguide/javascript
    
        HTTP/1.1 301 Moved Permanently
        Location: https://github.com/styleguide/coffeescript

~~~
Zikes
I think it's neat that people can create languages that compile to JavaScript
so they can work in an environment that's more their style, but it really irks
me when they try to say those languages ARE JavaScript.

This isn't a debate as to whether or not CoffeeScript is better, easier,
cleaner, etc. It's a simple A does not equal B statement, and it's starting to
remind me of the way my boss says I'm "good at Java".

------
tszming
A good coding guideline should emphasize the importance of "consistency", so
if you tell me that..

"..my advice is to insert them (semicolons) immediately before the opening
parenthesis or square bracket in any statement that begins with one of those
tokens, or any which begins with one of the arithmetic operator tokens /, +,
or - if you should happen to write such a statement..."
(<http://mislav.uniqpath.com/2010/05/semicolons/>)

Then I would say it is really not a good idea.

------
mutewinter
Scanning through the Ruby styleguide for GitHub-specific changes I found this
gem:

"The and and or keywords are banned. It's just not worth it. Always use && and
|| instead."

 _sad trombone_

~~~
jeltz
Indeed, "and" and "or" are excellent for their intended use, for control flow.
Like explained by the style guide the Github one is based on.
<https://github.com/bbatsov/ruby-style-guide>

    
    
       # boolean expression
       if some_condition && some_other_condition
         do_something
       end
    
       # control flow
       document.saved? or document.save!

~~~
286c8cb04bda
I'm not sold on tossing "and" and "or" out the window, but wouldn't
"document.saved? or document.save!" read better as "document.save! unless
document.saved?"

~~~
jeltz
Agreed, it is not my example.

------
MLMcMillion
Can someone explain the use of // instead of /* */ for CSS comments? According
to what I've always known, // isn't even valid.

~~~
zefhous
They are using .scss, so // is valid there.

Prefixing each commented line is more efficient in text editing than wrapping
things in blocks. Editor support for mappings to comment out sections of text
are more consistent in supporting prefixing each line and removing that than
wrapping and unwrapping a selection with the block syntax.

Also, that way you can comment out a larger section and subsequently uncomment
a part of that section with a single action instead of uncommenting the entire
thing, then re-commenting the part that you still want commented out.

~~~
MLMcMillion
Ah, gotcha. I read "CSS" and just, you know, assumed "CSS".

------
martingordon

      Use def self.method to define singleton methods.
      ...
      # Also possible and convenient when you
      # have to define many singleton methods.
      class << self
    

I would argue against using "class << self" _especially_ when you have many
singleton methods. If the class is large enough, it's easy to miss the "class
<< self" and incorrectly read a class method as an instance method.

~~~
arthurschreiber
Usually you will have another level of indentation, so class methods shouldn't
be that easy to mistake for instance methods.

------
davidcann
I'd recommend adding:

* Alphabetize properties within each CSS rule

To here: <https://github.com/styleguide/css>

~~~
zefhous
I strongly prefer logically grouping related styles.

The only advantage from alphabetizing rules is perhaps slightly faster
scanning of rules, but I don't think it is even very helpful in doing that.
You generally don't have that many rules in a single style anyway so it's not
a problem that needs solving.

However, by grouping related styles I think there are a some small yet
worthwhile advantages. Grouped styles can reveal intention, while
alphabetizing does not at all. Grouped styles can also make refactoring
quicker and less tedious.

~~~
davidcann
I would agree with that if there were a defined, consistent logic, but I've
never seen that done well across multiple developers. After switching to
alphabetized rules, my CSS feels much more organized and I'd say is much
easier to scan and refactor.

------
mildavw

      # bad
      email_with_name = user.name + ' <' + user.email + '>'
    
      # good
      email_with_name = "#{user.name} <#{user.email}>"
    
      # better
      email_with_name = "%s <%s>" % [user.name, user.email]

~~~
sanderjd
Why is the latter better? It seems equally good, but less idiomatic and
certainly less obvious to most Ruby programmers.

~~~
gioele
The structure of strings like

    
    
      email_with_name = "%s <%s>" % [user.name, user.email]
    

can be easily identified even when many fields are added.

On the contrary, strings like

    
    
      email_with_name = "#{user.name} <#{user.email}>"
    

become quite cramped as soon as you use three or more fields.

~~~
sanderjd
I'm not sure what you mean by cramped, but I think that the interpolation
style is, on the contrary, much easier to read when you have multiple fields:

    
    
      puts "#{num} #{vessels} of #{liquid} on the #{where}, you #{verb1} one #{adverb1}, #{verb2} it #{adverb2}, #{num - 1} #{vessels} of #{liquid} on the #{where}"
      puts "%d %s of %s on the %s, you %s one %s, %s it %s, %i %s of %s on the %s", [ num, vessels, liquid, where, verb1, adverb1, verb2, adverb2, num - 1 ]
    

It's an extreme example, but you just read the first, while you have to think
about the second.

------
lundahl
I don't get why people are using RGB hex values. I guess all of us find it
much easier to read and understand rgb(230, 30, 30) than #e61e1e. And if we
don't have to support IE8, I think hsl(0, 80%, 51%) is even better.

------
jeltz
Interesting to see their choice in the never ending battle about the
indentation of "private" in ruby. The lack of a empty line below "private"
seems like it would make the code hard to read. The "private" could easily be
missed.

Currently I prefer using "private" indented to the same level as "def", with
no change of indentation of code after "private", and an empty line before and
after "private".

------
zalew
Ruby doesn't have something like PEP for Python?

~~~
chrisguitarguy
For those of you wondering what this is:
<http://www.python.org/dev/peps/pep-0008/>

------
cocoflunchy
What's the reason for recommending 2 space indents ? I find it easier to read
with 4 or even more spaces indent.

~~~
elliottcarlson
I was wondering the same thing.

Recently, a coworker and myself were debating the use of tabs vs. spaces - and
while I know this is a battle that has been going on for a while and won't end
any time soon - one of my points against spaces was due to readability. 2
space soft-tabs seems much harder to follow - while using hard tabs for
indentation, you are able to adjust your editor to visually work out what
suits you best (2 spaces, 4 spaces or even 8 spaces).

~~~
caw
My coworker does some funky blend of spaces and tabs. His tab key inserts 4
spaces, but if he tabs twice (8 characters), it becomes the tab character. He
says it works better when printing.

I can't for the life of me figure out how to replicate the effect in vim to be
able to read his files logically, and he can't tell me because he's an emacs
user.

~~~
obtu
Something like:

set ts=8 sw=4 et sta

(tabstops to 8 (the default), shift width to 4, expand tabs, smart tabs)

------
mapleoin
They should have an HTML guide which should say: don't write <img> tags which
set an image's size to 4x less than its original size, it will look pixelated.

------
epikur
I might be missing something very obvious, but what's the license on this?
Specifically, on the CSS buttons and the forms, not just the code formatting.

------
mike_ivanov
No mention of the maximum line length in the Ruby style guide. Sigh...

~~~
holman
We tend to stay under 80c for everything (minus views, which can be trickier).
Probably should add that to the guide.

------
secoif
If you're commenting on the dangers on no semis I would put money on the fact
you haven't given it a real try. Perhaps you tried it, had an issue once, and
immediately reverted. Its like critiquing a book you haven't read.

------
dos1
After reading this, I just want to say that I do not think semicolon-less
javascript is, in general, a good idea.

Development projects are almost always team efforts. And, unfortunately,
there's almost always one or two team members who aren't very good. Some of
you folks that only work on startups with brilliant people might disagree, but
in my experience most development teams have some bad apples who have let
their tech skills rot, or won't try for some reason or another.

These people are going to have a tremendous time just writing halfway
competent javascript (especially since it's probably not similar to their OOP
language of choice). Suggesting they write code in an uncommon way is just
begging for trouble. Most of the examples on the internet use semicolons, as
do most of the frameworks. In fact, I hope that members of my future teams
never see this javascript style guide or even know that it's possible to omit
semicolons in many cases.

I'm quite sure someday soon I'm going to hear this over the cube wall: "Hey,
GitHub doesn't use semicolons in their javascript so I won't either!" And then
I will be very, very sad.

~~~
lucisferre
Yeah, you save one character per line, and gain a lot more in cognitive
friction. Words to live by: "don't make me think" even about whether or not I
need a semi-colon here.

~~~
secoif
Dropped semicolons about 6 months ago and haven't had a problem even once.

Once you get into the habit, it requires zero extra effort. You just know when
to put them in, same way you just know when to use parens vs curlies.

Coding with semis is like coding with parens around every expression;
unnecessary and paranoid.

~~~
dos1
But why? Why drop the semicolons? What is the benefit? If the net result is
exactly the same, why try and be tricky? What is the point, other than you
_can_ do it. But there are many tricky things we _can_ do with programming
languages, but very few we _should_

~~~
viscanti
On a team of a sufficient size, dropping semicolons hurts. Someone will be
running a static analysis "lint" program in their editor, and it will always
flag those missing semicolons. That certainly adds additional cognitive
friction to those users, who constantly see the reminder to add the missing
semicolon.

I guess I've never understood the argument for omitting them. It seems like an
unnecessary trick. Coding guidelines should enforce the simplest possible
patterns and techniques.

~~~
secoif
Unlikely the default lint options are going to suit all teams anyway.
JSLint/JSHint can, and should be configured for your team's style.

