<commit_before># Scheme code conventions

- [Introduction](#introduction)
- [Spacing](#srfi-libraries)
- [Line separation](#line-separation)
- [Indentation and alignment](#indentation-and-alignment)
- [Comments](#comments)
- [Names](#names)
- [Quotes](#quotes)

# Introduction 

This document presents a set of recommendations for Scheme code styling. Use them whenever possible. 

Most of the recommendations presented here follow, at least partially, [Riastradh's Lisp Style Rules](https://mumble.net/~campbell/scheme/style.txt) and scheme-wiki guides on [general Scheme style](http://community.schemewiki.org/?scheme-style), [variable naming conventions](http://community.schemewiki.org/?variable-naming-convention) and [comment style](http://community.schemewiki.org/?comment-style).

# Spacing

Lists inside lists should always be separated from other elements with **one** space.

  Not recommended:

```scheme
(foo(bar baz)quux)
(foo ( bar baz ) quux)
(foo  (bar baz)  quux)
```

  Recommended:

```scheme
(foo (bar baz) quux)
```

# Line separation

Do **not** place closing parentheses on their own lines. Scheme code is read through its indentation.

  NOT recommended:

```scheme
(define (factorial x)
  (if (< x 2)
      1
      (* x (factorial (- x 1
                      )
           )
      )
  )
)
```

  Recommended:

```scheme
(define (factorial x)
  (if (< x 2)
      1
      (* x (factorial (- x 1)))))
```

An exception may be when commenting out one line of code:

```scheme
(define (foo bar)
  (list (frob bar)
        (zork bar)
        ;; (zap bar)
        ))
```

But this is useful **only in development code**. For production code (ie. a package submission, Cyclone's code pull requests, etc) clean your code whenever possible.

A reasonable *permanent* exception is when dealing with long lists made to be expanded by *other people*, especially in files under version control. This eases the maintenance of the lists and clarifies version diffs. 

```scheme
(define colour-names         ;More colors are welcomed!
  '(blue
    cerulean
    green
    magenta
    purple
    red
    scarlet
    turquoise
    ))
```

# Indentation and alignment

We assume the following syntatic naming convention of elements in a list: 

    (operator operand1 operand2 ...)

So in `(+ 1 2 3 4)`, `+` is the `operator` and the numbers are the `operand`s.

For most `operator`s, `operand1` determines the alignment of the other `operand`s.

  NOT recommended:

```scheme
(+ (sqrt -1)
  (* x y)
  (+ p q))
```

  Recommended:

```scheme
(+ (sqrt -1)
   (* x y)
   (+ p q))

(cond ((null? l) (call-some-procedure))
      ((null? (car l)) (call-other-procedure))
      (else (recur-in-some-way))

(if (this-is-too-long-to-go-in-one-line)
    (do-this)
    (do-other-things))
```

If `operand1` is put in a different line from `operand`'s, it should be generally bellow `operand` (exceptions are discussed soon).

  NOT recommended:

```scheme
(+
   (sqrt -1)
   (* x y)
   (+ p q))
```

  Recommended:

```scheme
(+
 (sqrt -1)
 (* x y)
 (+ p q))

(cond 
 ((null? l) 
  (call-some-procedure))
 ((null? (car l)) 
  (call-other-procedure))
 (else (recur-in-some-way))

(if  ;not that recommended, but acceptable
 (this-is-too-long-to-go-in-one-line)
 (do-this)
 (do-other-things))
```

The same applies when the `operator` is a list, so 

  NOT recommended:

```scheme
((car x)
   (cdr x)
   foo)

((car x) (cdr x)
 foo)
```

  Recommended:

```scheme<commit_msg>Initial draft for Scheme code conventions<commit_after># Scheme code conventions

- [Introduction](#introduction)
- [Spacing](#srfi-libraries)
- [Line separation](#line-separation)
- [Indentation and alignment](#indentation-and-alignment)
- [Comments](#comments)
- [Names](#names)
- [Quotes](#quotes)

# Introduction 

This document presents a set of recommendations for Scheme code styling. Use them whenever possible. 

Most of the recommendations presented here follow, at least partially, [Riastradh's Lisp Style Rules](https://mumble.net/~campbell/scheme/style.txt) and scheme-wiki guides on [general Scheme style](http://community.schemewiki.org/?scheme-style), [variable naming conventions](http://community.schemewiki.org/?variable-naming-convention) and [comment style](http://community.schemewiki.org/?comment-style).

# Spacing

Lists inside lists should always be separated from other elements with **one** space.

  Not recommended:

```scheme
(foo(bar baz)quux)
(foo ( bar baz ) quux)
(foo  (bar baz)  quux)
```

  Recommended:

```scheme
(foo (bar baz) quux)
```

# Line separation

Do **not** place closing parentheses on their own lines. Scheme code is read through its indentation.

  NOT recommended:

```scheme
(define (factorial x)
  (if (< x 2)
      1
      (* x (factorial (- x 1
                      )
           )
      )
  )
)
```

  Recommended:

```scheme
(define (factorial x)
  (if (< x 2)
      1
      (* x (factorial (- x 1)))))
```

An exception may be when commenting out one line of code:

```scheme
(define (foo bar)
  (list (frob bar)
        (zork bar)
        ;; (zap bar)
        ))
```

But this is useful **only in development code**. For production code (ie. a package submission, Cyclone's code pull requests, etc) clean your code whenever possible.

A reasonable *permanent* exception is when dealing with long lists made to be expanded by *other people*, especially in files under version control. This eases the maintenance of the lists and clarifies version diffs. 

```scheme
(define colour-names         ;More colors are welcomed!
  '(blue
    cerulean
    green
    magenta
    purple
    red
    scarlet
    turquoise
    ))
```

# Indentation and alignment

We assume the following syntatic naming convention of elements in a list: 

    (operator operand1 operand2 ...)

So in `(+ 1 2 3 4)`, `+` is the `operator` and the numbers are the `operand`s.

For most `operator`s, `operand1` determines the alignment of the other `operand`s.

  NOT recommended:

```scheme
(+ (sqrt -1)
  (* x y)
  (+ p q))
```

  Recommended:

```scheme
(+ (sqrt -1)
   (* x y)
   (+ p q))

(cond ((null? l) (call-some-procedure))
      ((null? (car l)) (call-other-procedure))
      (else (recur-in-some-way))

(if (this-is-too-long-to-go-in-one-line)
    (do-this)
    (do-other-things))

(export proc1
        var1
        var2)
```

If `operand1` is put in a different line from `operand`'s, it should be generally bellow `operand` (exceptions are discussed soon).

  NOT recommended:

```scheme
(+
   (sqrt -1)
   (* x y)
   (+ p q))
```

  Recommended:

```scheme
(+
 (sqrt -1)
 (* x y)
 (+ p q))

(cond 
 ((null? l) 
  (call-some-procedure))
 ((null? (car l)) 
  (call-other-procedure))
 (else (recur-in-some-way))

(if  ;not that recommended, but acceptable
 (this-is-too-long-to-go-in-one-line)
 (do-this)
 (do-other-things))

(export 
 proc1
 var1
 var2)
```

The same applies when the `operator` is a list, so 

  NOT recommended:

```scheme
((car x)
   (cdr x)
   foo)

((car x) (cdr x)
 foo)
```

  Recommended:

```scheme
{'fraction_non_alphanumeric': 0.1404206935758954, 'fraction_numerical': 0.005969300739056282, 'mean_word_length': 3.2340553549939832, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7126237', 'n_tokens_mistral': 2482, 'n_tokens_neox': 2268, 'n_words': 786}