Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Why does JavaScript need a style guide? #102

Closed
ColemanGariety opened this issue Nov 10, 2013 · 43 comments
Closed

Why does JavaScript need a style guide? #102

ColemanGariety opened this issue Nov 10, 2013 · 43 comments

Comments

@ColemanGariety
Copy link

One of my favorite parts about the JavaScript community is that people choose to write it in so many different ways.

Why do you want to ruin that with a style guide?

Imagine if when Picasso was learning to paint, we told him what style he should paint in. Would we have cubism?

@hshoff
Copy link
Member

hshoff commented Nov 10, 2013

Hi @JacksonGariety, interesting example. Hope you don't mind if I run with it for a bit.

Let's say you start an e-commerce site.

Your first engineer is Picasso during his blue period. Your codebase quickly becomes filled with Picasso blue period javascript files. He paints you a javascript shopping cart without a problem. He's done it a million times before. But this is his best one. It's his masterpiece. And very blue.

Your second engineer is Salvador Dali. He shows up on his first day with a camera, a single paintbrush, a silly mustache, and starts contributing some crazy surrealist javascript files.

This influences Picasso as they work together and Picasso starts switching things up and begins adding cubism files to the codebase. The codebase is so new that Picasso and Dali can continue adding new files at any time with no harm, because there is no maintenance when it's just two engineers adding new functionality. No one is stepping on each other's toes. There's enough paint for everyone.

Then you hire Monet and he comes in and leaves his impression on everything.

Now you have a blue period shopping cart, impressionist image lazy loading, surrealist photo slide show, and cubism style event tracking in /app/assets/javascripts. The javascripts folder becomes a museum.

Let's jump to the future 4 years later. Lots of major functionality has already been built. Picasso has left the company to pursue a company built on a guernica style. Your business focus has shifted a bit and you need someone to extend Picasso's blue period shopping cart to support collaborative shopping (lots of people sharing the same cart in realtime).

Luckily you just hired a rising star in javascript land that likes to spray paint things on the wall, his name is Banksy. So you tell Banksy, "Hey for your first job we need you to modify our shopping cart so it supports collaboration. Timing is really important for the big relaunch, fortunately this should be really easy because we already have Picasso's shopping cart and it's already a masterpiece. Just reuse that."

So Banksy goes in and spray paints over your Picasso shopping cart and makes it collaborative and you have a big successful relaunch.

A month later a bug report comes in about removing items from the shopping cart. Banksy is busy on another project, so you get Monet to go in and fix it.

Monet doesn't know how to use spray paint cans. So his attempts to fix it are sloppy. He breaks the build. He switches back to the brush and just paints over it, but it took a lot longer than it should have because of the time to understand and adopt an unfamiliar style.

When you have over 80 engineers contributing to one codebase, you quickly learn your usual ways of doing things don't work. So we try to turn everyone into Picasso. No matter where you jump in to the codebase, all the files are familiar and look like they were painted by you.

The most important thing, no matter what your preferred javascript style is, is to be consistent when working with a team or a large codebase that will have to be maintained in the future.

The style that works best for our team is our Picasso style since that's how it all started.

We open sourced our style guide so other teams could fork it and turn it into a Monet style guide or a Banksy style guide. Which is lots of fun to watch.

As an individual painter/engineer working on side projects and exploring all the wonderful things you can do with javascript, please throw conventions away and ignore everything anyone has ever said.

It's the only way the world will enjoy the next Picasso.

🍻

@ColemanGariety
Copy link
Author

@hshoff What a great answer, thank you.

My only fear is that people will abuse a single style guide to no end and code will become generic and timeless.

@kientran
Copy link

One would argue the most important code in the world is in fact generic and timeless. E.g. College Algorithm Textbooks.

@ColemanGariety
Copy link
Author

@kientran is that really the most important code in the world?

Or is the most important code the Linux kernel, or v8, or jQuery, or NodeJS?

Just because something is prevalent doesn't mean it's making a positive impact.

@6twenty
Copy link

6twenty commented Nov 11, 2013

@hshoff that's one of the best comments I've come across on GitHub. Nicely said!

@fmundaca
Copy link

@hshoff your example is awesome ! nice !

@jaseemabid
Copy link

@hshoff I wish I could <3/+1/fav/something that comment :)

@tmikaeld
Copy link

This is programmer poetry! So beautiful it makes you cry.. of pain.. of happiness... of sadness.. or anxiety.. when looking at your own code.

@morgante
Copy link

Any anti-coding style arguments for JavaScript apply equally well to any language. And, like for all languages (as @hshoff put so beautifully), a coding style improves readability, coordination, and maintainability.

@zeroxff
Copy link

zeroxff commented Nov 11, 2013

@hshoff great answer!

@rottmann
Copy link

Think not only on your code, think about every project from others.
Every time i use components from other developers, i had to read first the style of their programming, thats annoying.

@robknight
Copy link

You need a style guide to prevent pointless changes due to differences in style preference between contributors. If I find your 8-space indenting annoying and change it to two-space indenting (which is about three keystrokes in emacs), I'm either going to commit something like "Fixed indenting" which is going to take up a line in the git log, or I'm not going to mention it at all, which means that some other commit is going to involve changing every single line of a file, effectively obscuring the purpose of the commit. Even worse, either of these commits breaks git blame for the affected file.

A style guide is like a grammar - you need shared rules so that any changes you make to other people's code are about changes in meaning rather than changes in style.

@rowanu
Copy link

rowanu commented Nov 11, 2013

@hshoff's comment is also a masterpiece!

@robknight's point about avoiding "pointless changes between contributors" is key too. Different programmers will express themselves in different ways, even while adhering exactly to the same style guide.

@jh3y
Copy link

jh3y commented Nov 11, 2013

@hshoff's response is fantastic, A+.

@gtd
Copy link

gtd commented Nov 11, 2013

@hshoff to be fair though, if I could hire that level of talent I'd let them do what they damn well please :)

@M3kH
Copy link

M3kH commented Nov 11, 2013

@hshoff 👍

My short answer would be, you never think to disassembler a paint already did, or reuse his color. If you want do a frame from an old one you just paint over ( refactoring ) or you make a copy ( copy and paste refactoring ).

Btw Style Guide or Style Manual, are practice should be consider outside of your Creativity process, there are just breakables rules, needed to reduce the time spend for take a choose during your workflow, and solve already knows problems.

@evert0n
Copy link

evert0n commented Nov 11, 2013

Awesome! 👍

@adamjgray
Copy link

Then you hire Monet and he comes in and leaves his impression on everything.

I admit that I laughed pretty hard on this one.

I've always found that it helps to think of a style guide as not being a hindrance on your creativity but as the medium in which you do your work. I liken it to ensuring your using similar materials and colors when building a house. If you keep things consistent between everyone working on a project, the end-product comes out looking a lot better in the end.

Good work, and nice answer. 8)

@mmcgahan
Copy link

@JacksonGariety, code should absolutely be generic and timeless - it's the product that should be revolutionary. As software engineers, it's easy for us to get stuck in the trap of thinking we're coding for coding's sake - that the libraries and scripts we write are the primary value of what we do. In reality (outside of academia and toy projects), code is judged by what it accomplishes, and in order to accomplish more, you have to make sure that it can be quickly accessed and modified by engineers with a variety of backgrounds. For that, you need something generic and timeless.

@orochi235
Copy link

@JacksonGariety I think your metaphor is a bit off. Code is less like painting and more like writing prose. It's also important to distinguish between style and convention.

Thousands upon thousands of great authors have written their entire oeuvre in English, and each has his or her own unique style. But they all follow the same conventions: periods end a sentence, followed by a space. Commas separate items in a list. Paragraph breaks separate ideas. And so on. The goal isn't to restrict the things that you can express in prose; it's to get the minutiae out of the way so that readers can focus on the bigger picture.

This is what coding style guides try to accomplish. They don't try to tell you how to solve a particular problem; they merely try to get the trivial crap out of the way so you can focus on the best solution.

@tinganho
Copy link

@hshoff I think this style guide lines only makes Salvador Dali and Banksy use the same pencils as Picasso. But that doesn't mean that that they will paint the in the same style as Picasso.

@rovolution
Copy link

@hshoff great post man!

@ded
Copy link

ded commented Nov 11, 2013

I can't even.

The consequences of not having a styleguide means your code will quickly become a mess in a short amount of time when multiple developers contribute.

If you think it's annoying to have to read someones styeguide before contributing, it will be far more annoying working in a codebase without any cohesiveness and consistency.

Imagine if you had to listen to a person speaking a language in 13 dialects with overtones of american, british, australian, and japanese accents. Your brain would spend more time just figuring out the words rather than the meaning of those words.

Thus, you're better off with a single dialect, even if its something a little more foreign.

@ColemanGariety
Copy link
Author

@hshoff @mmcgahan @orochi235 @ded I've thought about this quite a bit today and decided style-guides are a necessity, and permissible as long as they are living documents.

GitHub's open-source philosophy makes this easy, so I've forked airbnb/javascript to my own variation and strongly encourage others to do the same.

@hshoff
Copy link
Member

hshoff commented Nov 12, 2013

img

@hshoff hshoff closed this as completed Nov 12, 2013
@pablonoel
Copy link

citizen_cane

Sir, you just not only won the internet for today, but also show an incredible taste and knowledge about art and obviously history.

As a designer learning to code, or vice versa sometimes, the importance not only of a guide of style, but also a GOOD guide of style its fundamental to achieve a good job, because in terms of reading and writing and therefore understanding it can make a huge difference, not only working with teams, but also with yourself in the time.

@roblarsen
Copy link

Or is the most important code the Linux kernel, or v8, or jQuery, or NodeJS?

As an aside, all of those projects have their own associated code style guides

An aside to my aside, I quote this (from Idiomatic JS) all the time:
"All code in any code-base should look like a single person typed it, no matter how many people contributed."

@khakiout
Copy link

@hshoff wow, that's a great explanation. 👍

@subdigit
Copy link

Picasso and Dali eh? Just in case you need a visual reference for the differences that could be faced.

oeuf

Source

@timofurrer
Copy link
Contributor

@hshoff best post I read the last few weeks on GitHub! Thank you man 🍻

@mjtprivate
Copy link

I'd argue that what @hshoff says is really just a corollary to idea of Conceptual Integrity as defined in The Mythical Man Month by Fred Brooks. You need a level of integrity in all domains, from UI to code base.

This book may be 40 years old, but it still has a lot to say. His analogy of building cathedrals over along period of time sums up the problem brilliantly.

Ultimately a generic style guide for javascript is a somewhat doomed concept, implying you can squeeze out innovation and stand still. However, at the project level it is a completely different ball game.

@lindaliukas
Copy link

@hshoff absolutely loved this. Thank you.

@JuanitoFatas
Copy link

@hshoff Love this example, Awesome!

@ColemanGariety
Copy link
Author

@roblarsen @hshoff this is what I fundamentally disagree with.

In the end, people will find art in anything which is sustained. There is art wherever there are artists, and Crockford seems to want to snub this.

Why?

@roblarsen
Copy link

I'm not sure you're reading the same quote I am. Or you just think so differently about the importance of choosing where your spaces and brackets go that we may never meet in the middle.

To me, and I think the vast majority of people I've worked with, both on open source projects and on small to huge teams, the question of coding standards is something that you have to get out of the way before you get to the part where the true creativity shows- solving novel problems, creating outstanding interactions and the like. If missing out on solving the question of tabs vs. spaces is going to kill your art on a project, you're doing the wrong kind of projects.

In the past I've helped write and maintain publicly available standards documents as well as internal documents for some pretty big organizations and I can say from experience the work that informed the standards was much more rewarding, creatively, than codifying them into common patterns.

@roblarsen
Copy link

FWIW, the same applies when I'm working as a writer. Publishers have standards that they want you to follow. It's not a big deal. It's just the framework in which the fun stuff happens. Figuring out whether or not email should have a hyphen or if the Web is the "Web" or the "web" is just a detail.

@ColemanGariety
Copy link
Author

@roblarsen entirely subjective. I'm not in opposition to style guides, as much as I am in opposition to the idea that following publishers standards is "not a big deal."

@roblarsen
Copy link

Yeah, it's not a big deal to me, at all. Doing one of these things, at a level of useful detail, is a pain in the ass. Trust me on this. So if I can leverage an already published and maintained resource, I'm going to do it. It's not work where I'm going to add real value, especially when there are excellent resources out there to choose from based on style and level of detail. And, really, anything you disagree with in one of these things, you can alter for internal consumption if you really must.

It's like the choice between writing your own cross browser utility library or MVC framework. There's no point in doing that as, again, the real value I add is in solving the specific problems of the site or app I'm working on, not rewriting jQuery.

@deerawan
Copy link

deerawan commented Dec 4, 2014

Absolutely agree that we always need coding style guide to make our how to write codes similar and comfortable to each programmers.

@angelcervera
Copy link

@roblarsen Two important examples (maybe, the most important):

@simoniong
Copy link

@hshoff really amazing example! Love it!

@cliffjones
Copy link

It always strikes me as silly when people make arguments against standardization because they feel like it infringes on their artistic rights. You're free to be as avant-garde as you want on your own time.

Following the painting analogy, it's worth pointing out that Michelangelo didn't paint the whole Sistine Chapel ceiling himself. He managed a bunch of junior painters who all had to rigidly adhere to the "Michelangelo style" so the final product would hold together as a unit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests