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