From 1b5a467cb63b22f2b67b01c1d36e9bdc47839cfe Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 10 Apr 2014 14:49:08 -0500 Subject: [PATCH 01/17] initial style.md --- style.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 style.md diff --git a/style.md b/style.md new file mode 100644 index 00000000..7bda69d1 --- /dev/null +++ b/style.md @@ -0,0 +1,9 @@ +# Style + +## Go + +## CoffeeScript + +## Python + +## Bash From cd5ca1450badb23ff088c7f4e8bf3a0476216471 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 10 Apr 2014 15:11:52 -0500 Subject: [PATCH 02/17] style intro --- style.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/style.md b/style.md index 7bda69d1..ca12ca91 100644 --- a/style.md +++ b/style.md @@ -1,5 +1,15 @@ # Style +This document explains the standards we have around code style in various different languages. +Style is important to standardize for a few reasons: + +* Makes code more readable, and thus easier to understand. +* Avoids holy wars over small details, but still encourages an approach to coding that sweats the details. + +For each of the languages below we link to a style guide reference and outline tools to use in order to help follow the style guide. +These tools should be part of every project's build and test cycle. +As a code reviewer, you should hold people accountable to following the style guide for the appropriate language. + ## Go ## CoffeeScript From e7a53058cf95946b317ba010c99a9dde515849c4 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 10 Apr 2014 15:16:29 -0500 Subject: [PATCH 03/17] style: bash --- style.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/style.md b/style.md index ca12ca91..5d41e3f6 100644 --- a/style.md +++ b/style.md @@ -17,3 +17,6 @@ As a code reviewer, you should hold people accountable to following the style gu ## Python ## Bash + +The [Google Shell Style Guide](https://google-styleguide.googlecode.com/svn/trunk/shell.xml) is what we follow for shell scripts. +There are no automated tools that we use for following this, however there is [ShellCheck](http://www.shellcheck.net/about.html) which covers some of what's in the style guide. \ No newline at end of file From f6c5639788fd0a228fae251c35c2d95ca0f4d2b3 Mon Sep 17 00:00:00 2001 From: Jeffrey Nelson Date: Thu, 10 Apr 2014 13:44:27 -0700 Subject: [PATCH 04/17] style: go --- style.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/style.md b/style.md index 5d41e3f6..ea752ed0 100644 --- a/style.md +++ b/style.md @@ -12,6 +12,11 @@ As a code reviewer, you should hold people accountable to following the style gu ## Go +The style guides used for Go are [Effective Go](http://golang.org/doc/effective_go.html) and the community [Go style guide]. There are two tools that can be used to detect common mistakes. + +* `go fmt` should be run in any directory that contains go files. It will automatically format the code. +* `golint file.go` should be run for every go file. It will lint the code and return any issues it finds. + ## CoffeeScript ## Python From 488f276d7a5899a8e670366ade15760806b3e95e Mon Sep 17 00:00:00 2001 From: Jeffrey Nelson Date: Tue, 15 Apr 2014 14:20:19 -0700 Subject: [PATCH 05/17] Add link to community style guide. --- style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style.md b/style.md index ea752ed0..bc47f3b5 100644 --- a/style.md +++ b/style.md @@ -12,7 +12,7 @@ As a code reviewer, you should hold people accountable to following the style gu ## Go -The style guides used for Go are [Effective Go](http://golang.org/doc/effective_go.html) and the community [Go style guide]. There are two tools that can be used to detect common mistakes. +The style guides used for Go are [Effective Go](http://golang.org/doc/effective_go.html) and the community [Go style guide](https://code.google.com/p/go-wiki/wiki/CodeReviewComments). There are two tools that can be used to detect common mistakes. * `go fmt` should be run in any directory that contains go files. It will automatically format the code. * `golint file.go` should be run for every go file. It will lint the code and return any issues it finds. From 953c85656926f0e3452a2cc7bd5e5a1618401b8f Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 14:23:12 -0700 Subject: [PATCH 06/17] adding recommended setups for Go --- style.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/style.md b/style.md index bc47f3b5..fc3af47e 100644 --- a/style.md +++ b/style.md @@ -17,6 +17,13 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ * `go fmt` should be run in any directory that contains go files. It will automatically format the code. * `golint file.go` should be run for every go file. It will lint the code and return any issues it finds. +### Recommended setups + +* Makefiles +* emacs +* sublime +* vim + ## CoffeeScript ## Python From b6712f3b5b69ca6a384ccfe485b42030eb58ea9e Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 14:26:46 -0700 Subject: [PATCH 07/17] Go makefile guidelines --- style.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/style.md b/style.md index fc3af47e..5cff4b35 100644 --- a/style.md +++ b/style.md @@ -19,7 +19,16 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ### Recommended setups -* Makefiles +* Makefiles: A Go package should have a Makefile that runs "golint" on all files, e.g. + ```Makefile + $(PKG): + ifeq ($(LINT),1) + golint $(GOPATH)/src/$@*/**.go + endif + go test + ... + ``` + See [clever-go](https://github.com/Clever/clever-go/blob/master/Makefile) for an example. * emacs * sublime * vim From aceab03e735e58fc3d2ae87172b5cdf286643710 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 14:27:46 -0700 Subject: [PATCH 08/17] markdown --- style.md | 1 + 1 file changed, 1 insertion(+) diff --git a/style.md b/style.md index 5cff4b35..63458436 100644 --- a/style.md +++ b/style.md @@ -20,6 +20,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ### Recommended setups * Makefiles: A Go package should have a Makefile that runs "golint" on all files, e.g. + ```Makefile $(PKG): ifeq ($(LINT),1) From 6563128c8025e974ccfc2423ed490adb5268a484 Mon Sep 17 00:00:00 2001 From: Jeffrey Nelson Date: Tue, 15 Apr 2014 14:28:29 -0700 Subject: [PATCH 09/17] Add go for sublime. --- style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style.md b/style.md index fc3af47e..c9344b9e 100644 --- a/style.md +++ b/style.md @@ -21,7 +21,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ * Makefiles * emacs -* sublime +* sublime: Add [GoSublime](https://github.com/DisposaBoy/GoSublime) for code highlighting and `go fmt` on save. * vim ## CoffeeScript From ee6000081e1cdfe1db32785f939066bf81afaeff Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 14:31:06 -0700 Subject: [PATCH 10/17] Go emacs setup --- style.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/style.md b/style.md index 99dcc595..46014d4a 100644 --- a/style.md +++ b/style.md @@ -30,7 +30,12 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ... ``` See [clever-go](https://github.com/Clever/clever-go/blob/master/Makefile) for an example. -* emacs +* emacs: Go has an official [emacs mode](http://golang.org/misc/emacs/go-mode.el) that ships with a `gofmt` command. To get it to run on save, you can add this to your `.emacs`: + + ``` + (add-hook 'before-save-hook 'gofmt-before-save) + ``` + * sublime: Add [GoSublime](https://github.com/DisposaBoy/GoSublime) for code highlighting and `go fmt` on save. * vim From 84d7753119830251527b158bf6d3bcb16f835f6b Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 14:31:36 -0700 Subject: [PATCH 11/17] vim TODO --- style.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/style.md b/style.md index 46014d4a..5a20161d 100644 --- a/style.md +++ b/style.md @@ -37,7 +37,8 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ``` * sublime: Add [GoSublime](https://github.com/DisposaBoy/GoSublime) for code highlighting and `go fmt` on save. -* vim + +* vim (TODO) ## CoffeeScript From 2fa3b135e67215f66be2496626ae1f264674864d Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 15:05:37 -0700 Subject: [PATCH 12/17] python --- style.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/style.md b/style.md index 5a20161d..dba856e2 100644 --- a/style.md +++ b/style.md @@ -44,6 +44,31 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ## Python +The style guide we use is [PEP8](http://legacy.python.org/dev/peps/pep-0008/) with exceptions for allowing tab widths of two spaces and line lengths of up to 100. + +### Recommended setups + +PEP8 has an accompanying command-line tool, `pep8` (`pip install pep8`) that accepts a config file: + +``` +[pep8] +ignore = E111 +max-line-length = 100 +``` + +There is also the tool `autopep8` (`pip install autopep8`) that will fix all the problems found by `pep8`. + +* emacs: You can run `autopep8` on save by installing [`py-autopep8`](https://github.com/paetzke/py-autopep8.el) and adding the following to your `.emacs`: + + ```Makefile + (add-hook 'before-save-hook 'py-autopep8-before-save) + (setq py-autopep8-options '("--max-line-length=100" "--indent-size=2")) + ``` + +* vim: https://github.com/tell-k/vim-autopep8 + +* sublime: https://github.com/wistful/SublimeAutoPEP8 + ## Bash The [Google Shell Style Guide](https://google-styleguide.googlecode.com/svn/trunk/shell.xml) is what we follow for shell scripts. From 808f4ff6f593a9e62554af9270df1848ed24d897 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Tue, 15 Apr 2014 15:21:30 -0700 Subject: [PATCH 13/17] setups/setup --- style.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/style.md b/style.md index dba856e2..88bd25ac 100644 --- a/style.md +++ b/style.md @@ -17,7 +17,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ * `go fmt` should be run in any directory that contains go files. It will automatically format the code. * `golint file.go` should be run for every go file. It will lint the code and return any issues it finds. -### Recommended setups +### Recommended setup * Makefiles: A Go package should have a Makefile that runs "golint" on all files, e.g. @@ -46,7 +46,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ The style guide we use is [PEP8](http://legacy.python.org/dev/peps/pep-0008/) with exceptions for allowing tab widths of two spaces and line lengths of up to 100. -### Recommended setups +### Recommended setup PEP8 has an accompanying command-line tool, `pep8` (`pip install pep8`) that accepts a config file: From 765b53e3e12aab052d11ffc5133b6b125d48ee6c Mon Sep 17 00:00:00 2001 From: Jeffrey Nelson Date: Tue, 15 Apr 2014 15:25:13 -0700 Subject: [PATCH 14/17] Added CoffeeScript style. --- style.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/style.md b/style.md index dba856e2..87221f38 100644 --- a/style.md +++ b/style.md @@ -42,6 +42,8 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ## CoffeeScript +The style guide used for CoffeeScript can be found [here](https://github.com/Clever/coffeescript-style-guide). [coffeelint](https://github.com/clutchski/coffeelint) should be added as a test. The coffeelint config can be found [here](https://github.com/Clever/coffeescript-style-guide/blob/master/coffeelint-config.json). + ## Python The style guide we use is [PEP8](http://legacy.python.org/dev/peps/pep-0008/) with exceptions for allowing tab widths of two spaces and line lengths of up to 100. From 6f0e02c3047a05d904be290ad055ed94d859b781 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 17 Apr 2014 11:57:08 -0700 Subject: [PATCH 15/17] justify why it's important to do checks during build/test --- style.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/style.md b/style.md index 9cc6d59f..591843c0 100644 --- a/style.md +++ b/style.md @@ -7,7 +7,8 @@ Style is important to standardize for a few reasons: * Avoids holy wars over small details, but still encourages an approach to coding that sweats the details. For each of the languages below we link to a style guide reference and outline tools to use in order to help follow the style guide. -These tools should be part of every project's build and test cycle. +Making sure you follow these guidelines is at the same level of importance of making sure tests pass, so the tools outlined below should be part of the build and test cycle for every project. +Doing it as part of the build and test cycle (as opposed to elsewhere, e.g. git hooks) ensures that no code is merged into master that fails these checks and allows for maximum flexibility during development. As a code reviewer, you should hold people accountable to following the style guide for the appropriate language. ## Go From 99ed3d25994cfc58cd3051a463a58d0b0705110f Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 17 Apr 2014 14:44:16 -0700 Subject: [PATCH 16/17] go + vim --- style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style.md b/style.md index 591843c0..ed710d13 100644 --- a/style.md +++ b/style.md @@ -39,7 +39,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ * sublime: Add [GoSublime](https://github.com/DisposaBoy/GoSublime) for code highlighting and `go fmt` on save. -* vim (TODO) +* vim: See the directions [here](http://tip.golang.org/misc/vim/readme.txt). It's strongly advised to set up `gofmt` on save. ## CoffeeScript From dbf767c706c4ef6d3c137e80fcecd29266a0fae4 Mon Sep 17 00:00:00 2001 From: Jeffrey Nelson Date: Fri, 18 Apr 2014 13:36:28 -0700 Subject: [PATCH 17/17] Added coffee-jshint. --- style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style.md b/style.md index ed710d13..631a4145 100644 --- a/style.md +++ b/style.md @@ -43,7 +43,7 @@ The style guides used for Go are [Effective Go](http://golang.org/doc/effective_ ## CoffeeScript -The style guide used for CoffeeScript can be found [here](https://github.com/Clever/coffeescript-style-guide). [coffeelint](https://github.com/clutchski/coffeelint) should be added as a test. The coffeelint config can be found [here](https://github.com/Clever/coffeescript-style-guide/blob/master/coffeelint-config.json). +The style guide used for CoffeeScript can be found [here](https://github.com/Clever/coffeescript-style-guide). [coffeelint](https://github.com/clutchski/coffeelint) and [coffee-jshint](https://github.com/Clever/coffee-jshint) should be added as a test. The coffeelint config can be found [here](https://github.com/Clever/coffeescript-style-guide/blob/master/coffeelint-config.json). ## Python