git.cworth.org Git - sup/blob - HACKING

   1 Running Sup from your git checkout
   2 ----------------------------------
   3
   4 Invoke it like this:
   5
   6   ruby -I lib -w bin/sup
   7
   8 You'll have to install all gems mentioned in the Rakefile (look for the line
   9 setting p.extra_deps). If you're on a Debian or Debian-based system (e.g.
  10 Ubuntu), you'll have to make sure you have a complete Ruby installation,
  11 especially libssl-ruby. You will need libruby-devel, gcc, and make installed
  12 to build certain gems like Ferret. Gem install does not do a good job of
  13 detecting when these things are missing and the build fails.
  14
  15 Rubygems also is particularly aggressive about picking up libraries from
  16 installed gems. If you do have Sup installed as a gem, please examine
  17 backtraces to make sure you're loading files from the repository and NOT from
  18 the installed gem before submitting any bug reports.
  19
  20 Coding standards
  21 ----------------
  22
  23 - Don't wrap code unless it really benefits from it.
  24 - Do wrap comments at 72 characters.
  25 - Old lisp-style comment differentiations:
  26    # one for comments on the same line as a line of code
  27    ## two for comments on their own line, except:
  28    ### three for comments that demarcate large sections of code (rare)
  29 - Use {} for one-liner blocks and do/end for multi-line blocks.
  30 - I like poetry mode. Don't use parentheses unless you must.
  31 - The one exception to poetry mode is if-statements that have an assignment in
  32   the condition. To make it clear this is not a comparison, surround the
  33   condition by parentheses. E.g.:
  34     if a == b                    if(a = some.computation)
  35       ...             BUT          ... something with a
  36     end                          end
  37 - and/or versus ||/&&. In Ruby, "and" and "or" bind very loosely---even
  38   more loosely than function application. This makes them ideal for
  39   end-of-line short-circuit control in poetry mode. So, use || and &&
  40   for ordinary logical comparisons, and "and" and "or" for end-of-line
  41   flow control. E.g.:
  42     x = a || b or raise "neither is true"