Macaulay2 / Macaulay2/M2

Style guide and linter for M2 code

Open
#3,290 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

editors
Dominant language
Macaulay2
Stars
435
Forks
297
Avg merge
4d 20h
Merged PRs (30d)
11

Description

(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!


  1. Break any of the rules below when necessary for readability.
  2. Use 4 space indents inside code after opened (, {, [, <|.
  3. 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
    )
  1. 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,
    }
  1. When plausible, use spaces to tabulate keys and values in hash tables, e.g.
blah = method(
    Options => {
        Strategy    => null,
        LengthLimit => infinity,
        }
    )
  1. 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)
///
  1. Use tabs for each 8 spaces and remove extra spaces before the tab character.
  2. Insert a space after each comma in sequence of different types, e.g. (n, R, M).
  3. Dropping the space is fine in sequences of same type, e.g. [x,y,z].
  4. Insert a comma after the last item in hash tables, export lists, etc., e.g.
export {
    "blah",
    "foo",
    }
  1. 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
  1. Put a space before and after binary operators like = := -> => < ? | xor

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue contains proposed M2 style rules and examples, but names no source files, tests, or linter entry point. Start by resolving the style-guide suggestions and locating the M2 lexer or parser tooling; done would require an agreed guide and a basic linter whose behavior is tested against the listed formatting cases.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.