From 80da99a79c682f1b14d941be5d5d3cdb6526f447 Mon Sep 17 00:00:00 2001 From: Tim Hordern Date: Mon, 6 Apr 2015 15:16:27 -0400 Subject: [PATCH] Fix code blocks, some bullet indenting and add SCSS highlighting --- front-end/sass.md | 10 ++-- rspec.md | 5 ++ ruby.md | 113 +++++++++++++++++++++++++--------------------- sass.md | 18 ++++---- 4 files changed, 80 insertions(+), 66 deletions(-) diff --git a/front-end/sass.md b/front-end/sass.md index 9d93968..624b89e 100644 --- a/front-end/sass.md +++ b/front-end/sass.md @@ -72,7 +72,7 @@ What goes where? For example: -```` +````scss .my-class { @include adjust-font-size-to($medium-font-size); @include border-radius(5px); @@ -124,7 +124,7 @@ For example: * Use variables for repeated values within a file or class declaration * e.g. `_nav.scss` - ```` + ````scss $nav_height: 50px; nav { height: $nav_height; } #main { margin-top: $nav_height*-1; } @@ -173,7 +173,7 @@ SASS is code. Use it as such where appropriate. * Placeholders, unlike mixins, take advantage of selector grouping to avoid duplicating code * To use a placeholder, extend it: - ```` + ````scss %center { margin: 0 auto; padding: 10px 5px @@ -192,9 +192,9 @@ Use `!important` proactively, not reactively. * Only when we know that we want a style to take precedence over all other variations should we use `!important`. * For example, we might know that we **always** want an error message to appear red, regardless of text color of the module it appears in - ```` + ````scss .error { color: #e32!important; } ```` - + * If we find we need to use `!important` to force an override of a style, however, we need to instead go back and reconsider how that styling was written. diff --git a/rspec.md b/rspec.md index 839587a..769ed29 100644 --- a/rspec.md +++ b/rspec.md @@ -85,6 +85,7 @@ You can generate a PDF or an HTML copy of this guide using # bad it "should return true" + ``` * Write expectations at a high level, removed from logic and implementation details. @@ -105,6 +106,7 @@ You can generate a PDF or an HTML copy of this guide using * Use `describe` for concepts which don't in themselves vary (e.g. "callbacks, validations, "). Typically these are nouns. * Name `describe` blocks as follows: + * use "description" for non-methods * use pound "#method" for instance methods * use dot ".method" for class methods @@ -152,6 +154,7 @@ You can generate a PDF or an HTML copy of this guide using are likely to represent reality after future refactoring. * Valid reasons to use stubs/mocks: + * Performance: To prevent running a slow, unrelated task. * Determinism: To ensure the test gives the same result each time. e.g. Time.now, Kernel#rand, external web services. @@ -226,6 +229,7 @@ You can generate a PDF or an HTML copy of this guide using * Mock the models and stub their methods. Testing the controller should not depend on the model creation. * Test only the behaviour the controller should be responsible about: + * Execution of particular methods * Data returned from the action - assigns, etc. * Result from the action - template render, redirect, etc. @@ -364,6 +368,7 @@ which should be validated. Using `be_valid` does not guarantee that the problem ### Mailers * The mailer spec should verify that: + * the subject is correct * the receiver e-mail is correct * the e-mail is sent to the right e-mail address diff --git a/ruby.md b/ruby.md index 0ac1191..d14a793 100644 --- a/ruby.md +++ b/ruby.md @@ -217,6 +217,7 @@ You can generate a PDF or an HTML copy of this guide using puts "Done!" end + ``` * Do not leave empty lines after a class definition or between `end`s @@ -236,6 +237,7 @@ You can generate a PDF or an HTML copy of this guide using puts "Bar" end end + ``` * Align the parameters of a method call if they span over multiple lines. @@ -453,10 +455,12 @@ You can generate a PDF or an HTML copy of this guide using if x > 10 # body omitted end + ``` The one exception is when the condition contains an assignment, to signify intent: + ```Ruby # bad - should this have been a '=='? if x = self.next_value # body omitted @@ -518,6 +522,7 @@ You can generate a PDF or an HTML copy of this guide using # good names.select { |name| name.start_with?('S') }.map { |name| name.upcase } + ``` * Avoid `return` where not required. @@ -615,6 +620,7 @@ You can generate a PDF or an HTML copy of this guide using end end end + ``` * Use spaces around the `=` operator when assigning default values to method parameters: @@ -668,7 +674,7 @@ You can generate a PDF or an HTML copy of this guide using ``` * Don't use `||=` to initialize boolean variables. (Consider what -would happen if the current value happened to be `false`.) + would happen if the current value happened to be `false`.) ```Ruby # bad - would set enabled to true even if it was false @@ -690,10 +696,10 @@ would happen if the current value happened to be `false`.) * If the first argument to a method begins with an open parenthesis, always use parentheses in the method invocation. For example, write -`f((3 + 2) + 1)`. + `f((3 + 2) + 1)`. * When the keys of your hash are symbols use the Ruby 1.9 hash literal -syntax. + syntax. ```Ruby # bad @@ -729,23 +735,23 @@ syntax. * Don't use short (1 or 2 char) variable names unless it's a parameter of a single-line block: - ```Ruby - # ok - open(path) { |f| puts f.line } + ```Ruby + # ok + open(path) { |f| puts f.line } - # also ok - open(path) { |file| puts file.line } + # also ok + open(path) { |file| puts file.line } - # bad - open(path) do |f| - # ... - end + # bad + open(path) do |f| + # ... + end - # good - open(path) do |file| - # ... - end - ``` + # good + open(path) do |file| + # ... + end + ``` * Never shorten names by simply omitting a few letters (e.g. `search`, not `srch`; `response`, not `res`). @@ -770,8 +776,8 @@ syntax. (i.e. `Array#empty?` instead of `Array.is_empty?`) * The names of potentially "dangerous" methods (i.e. methods that modify `self` or the - arguments, `exit!` (doesn't run the finalizers like `exit` does), etc.) should end with an exclamation mark if - there exists a safe version of that *dangerous* method. + arguments, `exit!` (doesn't run the finalizers like `exit` does), etc.) should end with an + exclamation mark if there exists a safe version of that *dangerous* method. ```Ruby # bad - there is not matching 'safe' method @@ -821,14 +827,14 @@ syntax. this case, the bang version should be defined in terms of the non-bang one: - ```Ruby - class Thing - def save! - save or - raise Invalid.new(self) + ```Ruby + class Thing + def save! + save or + raise Invalid.new(self) + end end - end - ``` + ``` * Avoid "flag" parameters - write a separate method or take an options hash instead. @@ -910,7 +916,7 @@ syntax. ``` * Keep existing comments up-to-date. Favor explanatory commit messages instead. -An outdated comment is worse than no comment at all. + An outdated comment is worse than no comment at all. > Good code is like a good joke - it needs no explanation.
> -- Russ Olsen @@ -979,7 +985,7 @@ An outdated comment is worse than no comment at all. ``` * Use the `attr` family of functions to define trivial accessors or -mutators. + mutators. ```Ruby # bad @@ -1008,8 +1014,9 @@ mutators. end end ``` + * Consider using `Struct.new`, which defines the trivial accessors, -constructor and comparison operators for you. + constructor and comparison operators for you. ```Ruby # good @@ -1025,10 +1032,10 @@ constructor and comparison operators for you. # better Person = Struct.new(:first_name, :last_name) do end - ```` + ``` * Consider adding factory methods to provide additional sensible ways -to create instances of a particular class. + to create instances of a particular class. ```Ruby class Person @@ -1077,7 +1084,7 @@ to create instances of a particular class. ``` * Avoid the usage of class (`@@`) variables due to their "nasty" behavior -in inheritance. + in inheritance. ```Ruby class Parent @@ -1100,9 +1107,9 @@ in inheritance. over class variables. * Assign proper visibility levels to methods (`private`, `protected`) -in accordance with their intended usage. Don't go off leaving -everything `public` (which is the default). After all we're coding -in *Ruby* now, not in *Python*. + in accordance with their intended usage. Don't go off leaving + everything `public` (which is the default). After all we're coding + in *Ruby* now, not in *Python*. * Indent the `public`, `protected`, and `private` methods as much the method definitions they apply to. Leave one blank line above and below them. @@ -1118,6 +1125,7 @@ in *Ruby* now, not in *Python*. # ... end end + ``` * Use `def self.method` to define singleton methods. This makes the methods more resistant to refactoring changes. @@ -1278,17 +1286,17 @@ in *Ruby* now, not in *Python*. * Never use the `rescue` statement modifier, as there is no way to specify which exception classes to rescue. - ```Ruby - # bad - do_something rescue nil - - # good - begin - do_something - rescue SomeException - # ... - end - ``` + ```Ruby + # bad + do_something rescue nil + + # good + begin + do_something + rescue SomeException + # ... + end + ``` * Put more specific exceptions higher up the rescue chain, otherwise they'll never be rescued from. @@ -1314,7 +1322,7 @@ in *Ruby* now, not in *Python*. ``` * Release external resources obtained by your program in an ensure -block. + block. ```Ruby f = File.open('testfile') @@ -1328,12 +1336,12 @@ block. ``` * Favor the use of exceptions for the standard library over -introducing new exception classes. + introducing new exception classes. ## Collections * Prefer literal array and hash creation notation (unless you need to -pass parameters to their constructors, that is). + pass parameters to their constructors, that is). ```Ruby # bad @@ -1368,7 +1376,7 @@ pass parameters to their constructors, that is). * Avoid the use of mutable object as hash keys. * Use the new 1.9 literal hash syntax in preference to the hashrocket -syntax. + syntax. ```Ruby # bad @@ -1434,7 +1442,7 @@ syntax. line numbers so backtraces make sense. Note that if a heredoc is used, the correct line number is `__LINE__ + 1`. - ```ruby + ```Ruby class_eval <<-EOS, __FILE__, __LINE__ + 1 def #{method} end @@ -1451,7 +1459,7 @@ syntax. * call `super` at the end * delegate to assertive, non-magical methods: - ```ruby + ```Ruby # bad def method_missing(meth, *args, &block) if method =~ /\Afind_by_(?.*)/ @@ -1498,6 +1506,7 @@ syntax. * Use `OptionParser` for parsing complex command line options and `ruby -s` for trivial command line options. * Don't use File.join to piece together file names from static strings. + ```Ruby # bad path = File.join(Rails.root, 'config', 'blah.yml') diff --git a/sass.md b/sass.md index 52687de..2930575 100644 --- a/sass.md +++ b/sass.md @@ -72,7 +72,7 @@ Rules for where styles should go: For example: -```` +````scss .my_class { @include adjust-font-size-to($medium-font-size); @include border-radius(5px); @@ -130,7 +130,7 @@ In views: * Use variables for repeated values within a file or class declaration * for example: `_nav.scss` - ```` + ````scss $nav_height: 50px; nav { height: $nav_height; } #main { margin-top: $nav_height*-1; } @@ -210,7 +210,7 @@ and padding. BAD: -```` +````scss :sass .cyan { color: $cyan; } @@ -220,7 +220,7 @@ BAD: GOOD: -```` +````scss :sass #offer.booking span { color: $cyan; } @@ -276,7 +276,7 @@ For example: Decorators can return object state or method based classes. Use this as a way to move display differences exclusively into CSS - ```` + ````scss def price_classes classes = [] classes << 'membersOnly' if members_only @@ -287,17 +287,17 @@ Decorators can return object state or method based classes. Use this as a way t end ```` - ```` + ````scss .offerCard{ class: offer.price_classes } ```` - ```` + ````scss .pricing{ class: offer.price_classes } ```` Decorators can return computed html attributes nicely - ```` + ````scss def booking_form_attributes attrs = { url: h.offer_booking_path(self, secure: true), @@ -313,7 +313,7 @@ Decorators can return computed html attributes nicely end ```` - ```` + ````scss = form_for(@booking, offer.booking_form_attributes) do |f| ````