@@ -7,22 +7,18 @@
77
88# Hoon Style Guide
99
10−## Layout
10+Welcome to the Hoon style guide. It's important to
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.
12+## Layout
1513
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?)
14+Hoon's position on layout is: so long as your code is (a) correctly commented,
15+(b) free from blank or overlong lines, (c) parses, and (d) looks good, it's good
16+layout.
2117
2218When a layout standard or other fundamental coding convention is
2319not 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.
20+But Hoon's layout rules, though not rigid, are still strict. The
21+flavor should never overwhelm the content.
2622
2723### General outline of Hoon syntax
2824
@@ -48,27 +44,23 @@ or
4844```
4945
5046These are regular forms -- every rune can be written this way.
51−Hoon also has a variety of wide irregular forms. All tall
47+Hoon also has a variety of wide [irregular forms](/docs/reference/hoon-expressions/irregular). All tall
5248forms 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).
49+Almost all code has both wide and tall forms, the exception
50+being named cores.
5551
5652The goal of wide/tall forms is to resemble the look of
5753procedural code, with its statement/expression distinction,
5854in a purely functional language. In particular, complex code in
5955functional 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.
56+child nodes in the syntax tree are indented right.
6257
6358### Tall layout conventions
6459
6560In 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.
61+comments, either). In tall form, there is too much freedom, and so we need
62+conventions. These conventions aren't absolute, but
63+you shouldn't defy them unless you have a good reason to do so.
7264
7365Syntactically, there are three kinds of runes: fixed sequences,
7466variable sequences, and cores/engines. Let's talk about each.
@@ -121,7 +113,7 @@ It is sometimes acceptable to not backstep -- especially in tuple
121113runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:
122114for example: emphasizing symmetry in a tuple.
123115
124−#### Variable sequences
116+#### Variable sequences
125117
126118Variable sequences can have an arbitrary number of elements, so
127119they can't self-terminate. They are terminated by a `==` marker.
@@ -179,8 +171,8 @@ Queenside format:
179171```
180172
181173The 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.)
174+It is also usually hard to read without linebreak comments,
175+as demonstrated above.
184176
185177We sometimes end up with multiple terminators on separate lines,
186178two or more spaces apart. These lines can be collapsed:
@@ -222,7 +214,7 @@ two empty lines in a row in a Hoon file.
222214
223215Whitespace is semi-significant. The difference between a
224216space and a gap (more than one space) is significant. But two or
225−more spaces, newlines or comments are one gap.
217+more spaces, newlines, or comments are one gap.
226218
227219#### Comment conventions
228220
@@ -251,7 +243,7 @@ legitimate:
251243 this.is.more.code
252244```
253245
254−But more air is less often needed than you may think.
246+But air on both sides is needed less often than you may think.
255247
256248Crowded comments are comments on lines which also contain code.
257249Older code has a lot of these, especially the "column 56"
@@ -472,10 +464,8 @@ after the definition) has an explanation. This is obviously a
472464judgment call, as a grade of A should always be. If a definition
473465doesn't call for any explanation, it must be dead obvious.
474466
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.)
467+Two: every `%constant` we use must be defined where it is used,
468+not just where it's declared.
479469
480470The advantage of a `%constant` over a classic `typedef`: there is no
481471need to search formally for a symbol. The disadvantage: there is
@@ -483,7 +473,6 @@ no trivial way to find out what the symbol actually means. So
483473when I send some `%foobar` move, I should define what I think
484474`%foobar` means. Just copy and paste the original definition.
485475
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.
476+Code shouldn't even try for an A until it is quite stable. The worst
477+thing in the world is code that changes without updating the documentation.
478+Any *incorrect* comment in a file drops it all the way back to a D.