Style guide and linter for M2 code
Nobody has claimed this yet.
- 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!
- Break any of the rules below when necessary for readability.
- Use 4 space indents inside code after opened
(, {, [, <|. - 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
)
- 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,
}
- When plausible, use spaces to tabulate keys and values in hash tables, e.g.
blah = method(
Options => {
Strategy => null,
LengthLimit => infinity,
}
)
- 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)
///
- Use tabs for each 8 spaces and remove extra spaces before the tab character.
- Insert a space after each comma in sequence of different types, e.g.
(n, R, M). - Dropping the space is fine in sequences of same type, e.g.
[x,y,z]. - Insert a comma after the last item in hash tables, export lists, etc., e.g.
export {
"blah",
"foo",
}
- 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
- Put a space before and after binary operators like
= := -> => < ? | xor
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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