@@ -9,20 +9,14 @@
99
1010## Layout
1111
12−Layout in Hoon is an art. Hoon's position on layout is: so long
13−as your code is (a) correctly commented, (b) free from blank or
14−overlong lines, (c) parses, and (d) looks good, it's good layout.
15−
16−(Hoon does not accept the "gofmt" thesis that there is one true
17−layout. A heuristic algorithm could probably lay out decent
18−Hoon. Someone will probably write such an algorithm, which
19−doesn't mean they should. Why can't there be art in the world?
20−Why does everything have to be solved by robot?)
12+Hoon's position on layout is: so long as your code is (a) correctly commented,
13+(b) free from blank or overlong lines, (c) parses, and (d) looks good, it's good
14+layout.
2115
2216When a layout standard or other fundamental coding convention is
2317not perfectly rigid, code can develop some individual flavor.
24−But Hoon's layout rules, though not rigid, are still strict. So
25−the flavor should never overwhelm the content.
18+But Hoon's layout rules, though not rigid, are still strict. The
19+flavor should never overwhelm the content.
2620
2721### General outline of Hoon syntax
2822
@@ -48,27 +42,23 @@ or
4842```
4943
5044These are regular forms -- every rune can be written this way.
51−Hoon also has a variety of wide irregular forms. All tall
45+Hoon also has a variety of wide [irregular forms](. All tall
5246forms are regular. All code within a wide form is wide.
53−Almost all code has both wide and tall forms (the exception:
54−named cores).
47+Almost all code has both wide and tall forms, the exception
48+being named cores.
5549
5650The goal of wide/tall forms is to resemble the look of
5751procedural code, with its statement/expression distinction,
5852in a purely functional language. In particular, complex code in
5953functional languages tends to develop a diagonal shape, since
60−child nodes in the syntax tree are indented right. This shape
61−creates a constant struggle against the right margin.
54+child nodes in the syntax tree are indented right.
6255
6356### Tall layout conventions
6457
6558In wide form, the parser allows no freedom of layout (and no
66−comments, either). In tall form, there is too much freedom.
67−We need conventions.
68−
69−But -- if you really know what you're doing -- you can play with
70−these conventions. But don't do it just out of carelessness,
71−ego or boredom. Have a reason.
59+comments, either). In tall form, there is too much freedom, and so we need
60+conventions. These conventions aren't absolute, but
61+you shouldn't defy them unless you have a good reason to do so.
7262
7363Syntactically, there are three kinds of runes: fixed sequences,
7464variable sequences, and cores/engines. Let's talk about each.
@@ -121,7 +111,7 @@ It is sometimes acceptable to not backstep -- especially in tuple
121111runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:
122112for example: emphasizing symmetry in a tuple.
123113
124−#### Variable sequences
114+#### Variable sequences
125115
126116Variable sequences can have an arbitrary number of elements, so
127117they can't self-terminate. They are terminated by a `==` marker.
@@ -179,8 +169,8 @@ Queenside format:
179169```
180170
181171The queenside format is more useful when the tails are bigger.
182−(It is also usually hard to read without linebreak comments,
183−as shown above.)
172+It is also usually hard to read without linebreak comments,
173+as demonstrated above.
184174
185175We sometimes end up with multiple terminators on separate lines,
186176two or more spaces apart. These lines can be collapsed:
@@ -222,7 +212,7 @@ two empty lines in a row in a Hoon file.
222212
223213Whitespace is semi-significant. The difference between a
224214space and a gap (more than one space) is significant. But two or
225−more spaces, newlines or comments are one gap.
215+more spaces, newlines, or comments are one gap.
226216
227217#### Comment conventions
228218
@@ -251,7 +241,7 @@ legitimate:
251241 this.is.more.code
252242```
253243
254−But more air is less often needed than you may think.
244+But air on both sides is needed less often than you may think.
255245
256246Crowded comments are comments on lines which also contain code.
257247Older code has a lot of these, especially the "column 56"
@@ -472,10 +462,8 @@ after the definition) has an explanation. This is obviously a
472462judgment call, as a grade of A should always be. If a definition
473463doesn't call for any explanation, it must be dead obvious.
474464
475−Two: every `%constant` we use must be defined where it is used --
476−not just where it's declared. (Formal comment binding lets us
477−write one decoration hint at the base of an expression, even when
478−there are many uses of the same constant in the same code.)
465+Two: every `%constant` we use must be defined where it is used,
466+not just where it's declared.
479467
480468The advantage of a `%constant` over a classic `typedef`: there is no
481469need to search formally for a symbol. The disadvantage: there is
@@ -483,7 +471,6 @@ no trivial way to find out what the symbol actually means. So
483471when I send some `%foobar` move, I should define what I think
484472`%foobar` means. Just copy and paste the original definition.
485473
486−The A grade should be hard to earn. Code shouldn't even try for
487−an A until it is quite stable. The worst thing in the world is
488−code that changes without the documentation. Any *incorrect*
489−comment in a file drops it all the way back to a D.
474+Code shouldn't even try for an A until it is quite stable. The worst
475+thing in the world is code that changes without updating the documentation.
476+Any *incorrect* comment in a file drops it all the way back to a D.