Recent changes to Style

WikiPage Style modified by Alan Manuel Gloria

Alan Manuel Gloria — Sat, 11 Aug 2012 10:08:04 -0000

--- v23
+++ v24
@@ -228,3 +228,30 @@
     let1 x 2
       let1 y 3
         {x * y}
+
+Another alternative introduced in Readable 0.4 is to take advantage of the new SUBLIST-at-the-start semantics:
+
+    let
+      $ x 2
+      let
+        $ y 3
+        {x * y}
+
+One-armed `if`
+--------------
+
+In some Lisplike languages, a one-armed `if` exists called `when`:
+
+    when pred?(x)
+      do-one-thing()
+      do-another-thing()
+
+But this is hardly universal; Scheme does not define it in standards up to R6RS.
+
+An alternative would be to use the SUBLIST symbol together with a language's multi-expression sequencing form.  For example on Scheme:
+
+    if pred?(x) $ begin
+      do-one-thing()
+      do-another-thing()
+
+

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 21:14:12 -0000

--- v22
+++ v23
@@ -76,7 +76,7 @@
 Avoid unnecessary parentheses
 -----------------------------
 
-Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, and the name of the function is right after the indent, simply state the function followed by space-separated parameters.  So don't do this:
+Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, the name of the function is right after the indent, and there are no child lines, simply state the function followed by space-separated parameters.  So don't do this (assuming it has no child lines):
 
       myfunction(1 a(2) 3)

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:52:58 -0000

--- v21
+++ v22
@@ -156,7 +156,7 @@
 
 If you put both the condition and following expression(s) on the same line, make sure that you use the parenthetical versions of the actions.  Otherwise, each parameter will be interpreted as different actions.  Thus:
 
-    cond
+    cond  ; THIS IS ALMOST CERTAINLY WRONG
       {x < 0} frobnitz param1 param2 param3 param4 param5
 
 should probably be:

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:52:09 -0000

--- v20
+++ v21
@@ -55,20 +55,6 @@
 
 Use a consistent amount of indenting for each level. I tend to use 2 spaces for indentation; indentation nesting is more common in sweet-expressions, so 8-character indentations are often too much.
 
-Avoid unnecessary parentheses
------------------------------
-
-Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, and the name of the function is right after the indent, simply state the function followed by space-separated parameters.  So don't do this:
-
-      myfunction(1 a(2) 3)
-
-Instead, do this:
-
-      myfunction 1 a(2) 3
-
-The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
-
-This is one of the more debatable style recommendations.
 
 Use function call notation for parameters if they fit in a line
 ---------------------------------------------------------------
@@ -86,6 +72,21 @@
 
 Occasionally you may what to use function call notation even if the parameters won't fit in a line, because once inside a function call indentation processing isn't relevant - and that can be useful.
 
+
+Avoid unnecessary parentheses
+-----------------------------
+
+Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, and the name of the function is right after the indent, simply state the function followed by space-separated parameters.  So don't do this:
+
+      myfunction(1 a(2) 3)
+
+Instead, do this:
+
+      myfunction 1 a(2) 3
+
+The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
+
+This is one of the more debatable style recommendations.
 
 Beware of almost-function-call errors
 -------------------------------------

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:48:31 -0000

--- v19
+++ v20
@@ -7,13 +7,7 @@
 
 Whenever you have an infix expression, just surround it with {...}. You can use the form f(...) to call a function; if it has zero parameters, express it as f(), and if it has more than one parameter, separate the parameters with spaces. The f(...) form is especially handy for creating short expressions as a parameter on a line; for long expressions, use indentation instead.
 
-The symbol "\\\\" on a line by itself is used to define lists of lists in sweet-expressions. This makes it easy to create lists of lists, without having to create special syntax for each variation.
-
-This is all implemented by modifying the "read" function, so that it recognizes all these formats and generates s-expressions. Since macros operate on s-expressions, macros work just fine. You can have infix operators in macro definitions, and you can have infix operators in the expressions processed by macros.
-
-Interactively, you can just type *load("filename")* or *{3 + 2}*, then Enter Enter.
-
-Certain functions require groups, and you learn what they are (and their patterns) they're pretty easy to manage.
+Let's go through some specifics.
 
 
 Use infix notation

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:47:11 -0000

--- v18
+++ v19
@@ -61,6 +61,21 @@
 
 Use a consistent amount of indenting for each level. I tend to use 2 spaces for indentation; indentation nesting is more common in sweet-expressions, so 8-character indentations are often too much.
 
+Avoid unnecessary parentheses
+-----------------------------
+
+Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, and the name of the function is right after the indent, simply state the function followed by space-separated parameters.  So don't do this:
+
+      myfunction(1 a(2) 3)
+
+Instead, do this:
+
+      myfunction 1 a(2) 3
+
+The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
+
+This is one of the more debatable style recommendations.
+
 Use function call notation for parameters if they fit in a line
 ---------------------------------------------------------------
 
@@ -78,28 +93,13 @@
 Occasionally you may what to use function call notation even if the parameters won't fit in a line, because once inside a function call indentation processing isn't relevant - and that can be useful.
 
 
-Avoid unnecessary parentheses
------------------------------
-
-Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, simply state the function followed by space-separated parameters.  So don't do this:
-
-      myfunction(1 a(2) 3)
-
-Instead, do this:
-
-      myfunction 1 a(2) 3
-
-The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
-
-This is one of the more debatable style recommendations.
-
-
 Beware of almost-function-call errors
 -------------------------------------
 
 Remember that "f(x)" is completely different from "f (x)"; the former means the 2-element list "(f x)", while the latter means an atom followed by a single-element list, "f (x)". In sweet-expressions (and traditional Lisp notation), whitespace is a *separator*, so for sweet-expression prefixed function calls, be sure to *not* put a space between the function name and the open paren.
 
 You can put whitespace after the "(", or before the ")", and it'll make no difference, so "f(x)" and "f( x )" are equivalent. However, as a style I suggest *not* inserting this unnecessary space in most cases.  That way, any whitespace between an atom and open paren is "unusual" and will catch the eye, making it easier to read.
+
 
 Width
 -----

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:44:53 -0000

--- v17
+++ v18
@@ -81,7 +81,7 @@
 Avoid unnecessary parentheses
 -----------------------------
 
-Where it's understandable, don't include unnecessary parentheses. For example, when indentation processing is active, don't do this:
+Where it's understandable, don't include unnecessary parentheses. In particular, when indentation processing is active, simply state the function followed by space-separated parameters.  So don't do this:
 
       myfunction(1 a(2) 3)
 
@@ -91,7 +91,7 @@
 
 The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
 
-The is one of the more debatable style recommendations.
+This is one of the more debatable style recommendations.
 
 
 Beware of almost-function-call errors

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:42:42 -0000

--- v16
+++ v17
@@ -15,6 +15,18 @@
 
 Certain functions require groups, and you learn what they are (and their patterns) they're pretty easy to manage.
 
+
+Use infix notation
+------------------
+
+If the function is typically written as infix (including "+", "\*", "or", and "\<"), use {...} to write it as an infix value. Generally these operators will be "and", "or", or an operator that only uses punctuation. If you're calling a function with only one parameter, and that parameter is calculated with an infix operation, use the f{...} shorthand. You can see all of these suggestions in this example:
+
+    define factorial(n)
+      if {n <= 1}
+        1
+        {n * factorial{n - 1}} ; f{...} => f({...})
+
+However, you may want to keep using prefix form if indentation still matters and one or more of the parameters is exceedingly complex (e.g., it's nested very deeply or includes program structuring forms like "cond" and "define"). This situation can often occur with "and" and "or" if you're using a functional programming style.
 
 Use indentation for major program/data structure
 ------------------------------------------------
@@ -65,17 +77,6 @@
 
 Occasionally you may what to use function call notation even if the parameters won't fit in a line, because once inside a function call indentation processing isn't relevant - and that can be useful.
 
-Use infix notation
-------------------
-
-If the function is typically written as infix (including "+", "\*", "or", and "\<"), use {...} to write it as an infix value. Generally these operators will be "and", "or", or an operator that only uses punctuation. If you're calling a function with only one parameter, and that parameter is calculated with an infix operation, use the f{...} shorthand. You can see all of these suggestions in this example:
-
-    define factorial(n)
-      if {n <= 1}
-        1
-        {n * factorial{n - 1}} ; f{...} => f({...})
-
-However, you may want to keep using prefix form if indentation still matters and one or more of the parameters is exceedingly complex (e.g., it's nested very deeply or includes program structuring forms like "cond" and "define"). This situation can often occur with "and" and "or" if you're using a functional programming style.
 
 Avoid unnecessary parentheses
 -----------------------------

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:41:32 -0000

--- v15
+++ v16
@@ -1,7 +1,7 @@
 Here are some style guidelines that may help you create easy-to-read code.  We focus on sweet-expressions here.
 
-General Rules
--------------
+General Guidance
+----------------
 
 Mentally, this is pretty straightforward - on each line, write an expression; everything after the first term on the line, or all child lines, are parameters of the first term. You can use grouping operators ( ), [ ], and { } to put subexpressions on the same line, if you want. Use -( ... ) to negate something.
 
@@ -88,7 +88,7 @@
 
       myfunction 1 a(2) 3
 
-The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.
+The latter is easier for humans to read, because the human reader has one less pair of parentheses to track.  If you move it back to being later in the line (e.g., after a condition in "cond"), be sure to restore the function call parentheses.
 
 The is one of the more debatable style recommendations.

WikiPage Style modified by David A. Wheeler

David A. Wheeler — Mon, 30 Jul 2012 02:37:18 -0000

--- v14
+++ v15
@@ -1,4 +1,4 @@
-Here are some style guidelines for using sweet-expressions.
+Here are some style guidelines that may help you create easy-to-read code.  We focus on sweet-expressions here.
 
 General Rules
 -------------
@@ -15,11 +15,6 @@
 
 Certain functions require groups, and you learn what they are (and their patterns) they're pretty easy to manage.
 
-
-Suggestions for Style
-====================
-
-If you're using sweet-expressions, the bottom line for style is "make it easy to read". But here are a few suggestions that should help you do so in most cases. I presume an 80-character width for program text; sweet-expressions don't require them, but it can be annoying to handle overwide source code.
 
 Use indentation for major program/data structure
 ------------------------------------------------
@@ -105,11 +100,16 @@
 
 You can put whitespace after the "(", or before the ")", and it'll make no difference, so "f(x)" and "f( x )" are equivalent. However, as a style I suggest *not* inserting this unnecessary space in most cases.  That way, any whitespace between an atom and open paren is "unusual" and will catch the eye, making it easier to read.
 
+Width
+-----
+
+You should probably stick to an 80-character width for program text; sweet-expressions don't require them, but it can be annoying to handle overwide source code.  If you occasionally go over, it's not the end of the world, though you might want to reformat later.
+
 
 Indents
 -------
 
-Indenting is more common in sweet-expressions, so 2-space indents are often useful.  But the indent distance is up to you.
+Indenting is more common in sweet-expressions, so 2-space indents are often useful.  That's especially important if you're trying to stay within 80 columns.  Of course, the indent distance is up to you.
 
 You can use "!" as an indent character, just like space or tab.  This is helpful if you want to include sweet-expressions in a medium that hides indentation.  You can also use this to highlight a particular vertical group.  We suggest always following "!" with space or tab.  However, beware if you start a paired expression and let it continue to the next line; the "!" is *not* an indent character inside parentheses, braces, or brackets.