Style guide and linter for M2 code

[mahrud]

(I thought there was an issue about this already, but I can't find it.)

We need a basic linter for M2, but there needs to be a style guide first. We can use this issue to collect suggestions. I'll start with a few. Feedback for changing these are welcome!

---

0. Break any of the rules below when necessary for readability.
1. Use 4 space indents inside code after opened (, {, [, <|.
2. Use 4 space indents inside code after for, do, list, while, if, then, else, e.g.

if cond then (
    multi-line code 1
    )
else (
    multi-line code 2
    )

if cond
then result1
else result2

if cond then
    result1
else
    result2

while cond do
    stuff

while cond
do stuff

while cond do (
    multi-line stuff
    )

for i in range do
    stuff

for i in range
do stuff

for i in range do (
    multi-line stuff
    )

3. Use 4 spaces after -> and =>, e.g.

longMethodName Module := Module => opts -> (n, R, M) ->
    if n == 0 then R^1 else
    if n  > 0 then blah blah M else
    error "expected non-negative integer"

longMethodName Ideal := Module => opts -> (n, R, I) ->
    longMethodName(n, R, module I)

longMethodName Ideal := Module => opts ->
    (n, R, I) -> longMethodName(n, R, module I)

H = new HashTable from {
    "very very ......................................... very long key" =>
        12,
    }

4. When plausible, use spaces to tabulate keys and values in hash tables, e.g.

blah = method(
    Options => {
        Strategy    => null,
        LengthLimit => infinity,
        }
    )

5. Use 2 space indents inside documentation after things like Node, Key, ..., but one more or less for cases like this is acceptable:

doc ///
Node
  Key
    func
   (func, Module)
   (func, Sequence)
   [func, Strategy]
  Usage
    func M
    func(M,N)
  Inputs
     M:Module -- graded
   "(M,N)":
       a pair of modules
  SeeAlso
    func2
   (func, Ideal)
///

6. Use tabs for each 8 spaces and remove extra spaces before the tab character.
7. Insert a space after each comma in sequence of different types, e.g. (n, R, M).
8. Dropping the space is fine in sequences of same type, e.g. [x,y,z].
9. Insert a comma after the last item in hash tables, export lists, etc., e.g.

export {
    "blah",
    "foo",
    }

10. Don't use parenthesis around a single object:

blah(ZZ) := (n) -> (2*n) -- bad
blah ZZ := n -> 2*n      -- good

dim(module(I) -- bad
dim module I  -- good

coker(gens(I ** M)) -- good
coker gens(I ** M)  -- good

-- exception: functions which accept only a single object
func = (x) -> stuff

11. Put a space before and after binary operators like = := -> => < ? | xor

[d-torrance]

12. No trailing whitespace

[mahrud]

13. Use 2 space indents inside TEST.

[mahrud]

Related changes to discuss: Macaulay2/M2-emacs#32 Macaulay2/M2-emacs#77

[mikestillman]

I would prefer no TABS at all. Some editors use default 4, 8, and although I have a hot key to switch that in emacs myself, it makes code look bad if viewed with other default.

[mahrud]

14. No spurious new lines (e.g. see this file for what not to do)

[mikestillman]

At the end of a package, use end-- or end------------- instead of end