@@ -75,7 +75,9 @@ library please indicate that in the `Changelog` as `Breaking Changes` and what
7575the programmers need to do to adapt to the new change. Any new user visible
7676changes must be documented in the `Changelog`.
7777
78−## Coding Style
78+## Coding
79+
80+### Style
7981
8082As long as possible please try to match the style of the file or the
8183surrounding code. For haskell coding style guidelines, please [see this style
@@ -83,17 +85,28 @@ guide](https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
8385Specifically,
8486
8587* Please use 4 spaces for indentation.
86−* Do not let the code go beyond 79 columns
87−* Use multiline `let` clauses like this:
88− ```
89− let stop = stp
90− yield a Nothing = ...
91− ...
92− ```
93−* Align the contents of the where clause in the same column as the `where`
94− keyword for saving unnecessary indentation, like this:
95− ```
96− where
97−
98− x = ...
99− ```
88+* Do not let the code go beyond 80 columns
89+
90+### Organization
91+
92+Use this simple rule to organize functions in a file or even modules in the
93+cabal file - `Define before first use` or in other words use the `bottom up
94+style`. Note that this rule does not apply in choosing `let` vs `where`
95+clauses. Use of `let`s leads to bottom up and use of `where`s leads to top
96+down style. But we do not encourage `let` over `where`, you can freely use
97+`where` clauses. Also note that this is not possible in mutually recursive
98+code.
99+
100+One big benefit of this rule is easier type error debugging. It allows you to
101+cut a part of the code tree cleanly by commenting out the code in a file from
102+any point in the file up to the end of the file by just using a single comment
103+block and the uncommented code still compiles. That way we can incrementally
104+increase the uncommented portion by just sliding the beginning of the comment
105+further down in the file and compile the file. This way it is very easy to
106+incrementally compile the code and figure out the type errors in a smaller yet
107+complete code, this reduction in the scope of type inferencing makes it really
108+easy to figure out even hard to understand type errors.
109+
110+Similalrly when you put modules in the cabal file in dependency order you can
111+do the same there, just comment out a tail of the module list and the rest will
112+still compile.