@@ -9,20 +9,14 @@
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
12+Hoon's position on layout is: so long as your code is (a) correctly commented,
14−overlong lines, (c) parses, and (d) looks good, it's good layout.
13+(b) free from blank or overlong lines, (c) parses, and (d) looks good, it's good
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?)
22When a layout standard or other fundamental coding convention is
16When a layout standard or other fundamental coding convention is
23not perfectly rigid, code can develop some individual flavor.
17not perfectly rigid, code can develop some individual flavor.
24−But Hoon's layout rules, though not rigid, are still strict. So
18+But Hoon's layout rules, though not rigid, are still strict. The
25−the flavor should never overwhelm the content.
19+flavor should never overwhelm the content.
27### General outline of Hoon syntax
21### General outline of Hoon syntax
@@ -48,27 +42,23 @@ or
50These are regular forms -- every rune can be written this way.
44These 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
52forms are regular. All code within a wide form is wide.
46forms are regular. All code within a wide form is wide.
53−Almost all code has both wide and tall forms (the exception:
47+Almost all code has both wide and tall forms, the exception
54−named cores).
48+being named cores.
56The goal of wide/tall forms is to resemble the look of
50The goal of wide/tall forms is to resemble the look of
57procedural code, with its statement/expression distinction,
51procedural code, with its statement/expression distinction,
58in a purely functional language. In particular, complex code in
52in a purely functional language. In particular, complex code in
59functional languages tends to develop a diagonal shape, since
53functional languages tends to develop a diagonal shape, since
60−child nodes in the syntax tree are indented right. This shape
54+child nodes in the syntax tree are indented right.
61−creates a constant struggle against the right margin.
63### Tall layout conventions
56### Tall layout conventions
65In wide form, the parser allows no freedom of layout (and no
58In wide form, the parser allows no freedom of layout (and no
66−comments, either). In tall form, there is too much freedom.
59+comments, either). In tall form, there is too much freedom, and so we need
67−We need conventions.
60+conventions. These conventions aren't absolute, but
68−
61+you shouldn't defy them unless you have a good reason to do so.
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.
73Syntactically, there are three kinds of runes: fixed sequences,
63Syntactically, there are three kinds of runes: fixed sequences,
74variable sequences, and cores/engines. Let's talk about each.
64variable sequences, and cores/engines. Let's talk about each.
@@ -121,7 +111,7 @@ It is sometimes acceptable to not backstep -- especially in tuple
121runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:
111runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:
122for example: emphasizing symmetry in a tuple.
112for example: emphasizing symmetry in a tuple.
124−#### Variable sequences
114+#### Variable sequences
126Variable sequences can have an arbitrary number of elements, so
116Variable sequences can have an arbitrary number of elements, so
127they can't self-terminate. They are terminated by a `==` marker.
117they can't self-terminate. They are terminated by a `==` marker.
@@ -179,8 +169,8 @@ Queenside format:
181The queenside format is more useful when the tails are bigger.
171The queenside format is more useful when the tails are bigger.
182−(It is also usually hard to read without linebreak comments,
172+It is also usually hard to read without linebreak comments,
183−as shown above.)
173+as demonstrated above.
185We sometimes end up with multiple terminators on separate lines,
175We sometimes end up with multiple terminators on separate lines,
186two or more spaces apart. These lines can be collapsed:
176two or more spaces apart. These lines can be collapsed:
@@ -222,7 +212,7 @@ two empty lines in a row in a Hoon file.
223Whitespace is semi-significant. The difference between a
213Whitespace is semi-significant. The difference between a
224space and a gap (more than one space) is significant. But two or
214space 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.
227#### Comment conventions
217#### Comment conventions
@@ -251,7 +241,7 @@ legitimate:
251 this.is.more.code
241 this.is.more.code
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.
256Crowded comments are comments on lines which also contain code.
246Crowded comments are comments on lines which also contain code.
257Older code has a lot of these, especially the "column 56"
247Older code has a lot of these, especially the "column 56"
@@ -472,10 +462,8 @@ after the definition) has an explanation. This is obviously a
472judgment call, as a grade of A should always be. If a definition
462judgment call, as a grade of A should always be. If a definition
473doesn't call for any explanation, it must be dead obvious.
463doesn't call for any explanation, it must be dead obvious.
475−Two: every `%constant` we use must be defined where it is used --
465+Two: every `%constant` we use must be defined where it is used,
476−not just where it's declared. (Formal comment binding lets us
466+not just where it's declared.
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.)
480The advantage of a `%constant` over a classic `typedef`: there is no
468The advantage of a `%constant` over a classic `typedef`: there is no
481need to search formally for a symbol. The disadvantage: there is
469need 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
483when I send some `%foobar` move, I should define what I think
471when I send some `%foobar` move, I should define what I think
484`%foobar` means. Just copy and paste the original definition.
472`%foobar` means. Just copy and paste the original definition.
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
474+Code shouldn't even try for an A until it is quite stable. The worst
488−code that changes without the documentation. Any *incorrect*
475+thing in the world is code that changes without updating the documentation.
489−comment in a file drops it all the way back to a D.
476+Any *incorrect* comment in a file drops it all the way back to a D.