### 11` `Pyret Style Guide

Ahoy matey! Here be the style guide for Pyret. Follow me rules to find the hidden treasure, or walk the plank!

#### 11.1` `General

##### 11.1.1` `Indentation

You should indent your code blocks using two spaces (not tabs).

##### 11.1.2` `Line Length

Try to keep the total length of your lines under 80 characters.

For overly long lines, it’s actually really hard to figure out where to put in good line breaks. This is in every language. Look for something that tries to match the logical structure of your program.

fun f(x, y, z): |

g(some-very-long-thing(x * x, y + y), other-very-long-thing((x + y + z) / (2 * 3 * 4))) |

end |

fun f(x, y, z): |

sensible-name-1 = some-very-long-thing(x * x, y + y) |

sensible-name-2 = other-very-long-thing((x + y + z) / (2 * 3 * 4)) |

g(sensible-name-1, sensible-name-2) |

end |

Not only does this shorten lines, it makes it clearer what all these pieces are doing, helping a later reader (who may be yourself!).

##### 11.1.3` `Variable Naming

The programming language world rages about the use of camelCase versus under_scores in variable names. Pyret’s syntax supports both, but we can do better.

In Pyret, you can use dashes (-) inside variable names.This is sometimes called “kebab case”, but it would be more accurate to call it “shish case”. Thus, you would write camel-case and under-scores. Unlike underscores, dashes don’t need a shift key (or disappear when text is underlined by an environment). Unlike camelcase, dashes don’t create ambiguities (what if one of the words is in all-caps?). Dashes are also humanizing: they make your program look that little bit more like human prose.

Most languages can’t support dashes because the dash also stands for infix subtraction. In Pyret, subtraction must be surrounded by space. Therefore, camel-case is a name whereas camel - case is subtraction.

##### 11.1.3.1` `Naming Constants

MY-COUNT = 100 |

e = 2.7182 |

##### 11.1.3.2` `Reusing Variable Names

fun f(x): x + 1 end |

fun g(x): x + 2 end |

fun h(x): |

x = 4 |

x + 1 |

end |

##### 11.1.4` `File Naming

Use .arr as the extension for Pyret files.

##### 11.1.5` `Example and Tests

We use the syntax of testing to represent two different tasks: examples, which help us explore a problem and take steps towards deriving a solution, and tests, which are designed to find errors. These are subtly different.

examples: |

f(10) is 25 |

f(20) is-not 2000 |

end |

#### 11.2` `Functions

##### 11.2.1` `Naming

Give functions descriptive names. Do the same for arguments. That way, a quick scan of a function’s header will tell you what it does and what the arguments are supposed to do.

##### 11.2.2` `Documentation Strings

fun insert(x, l): |

doc: "consumes sorted list l; returns it with x in the right place" |

... |

end |

``` |

fun f(x): |

doc: ```This is a |

multi-line |

comment here.``` |

x + x |

end |

##### 11.2.3` `Annotations

fun str-len(str :: String) -> Number: |

# ... |

end |

fun length(lst :: List<Any>) -> Number: |

# ... |

end |

fun non-negative(n :: Number) -> Boolean: |

n >= 0 |

end |

fun sqrt(n :: Number%(non-negative)) -> Number: |

# ... |

end |

##### 11.2.4` `Testing

You should test every function you write for both general cases and edge cases.

fun double(n :: Number) -> Number: |

n * 2 |

where: |

double(0) is 0 |

double(5) is 10 |

double(-5) is -10 |

double(100) is 200 |

double(-100) is -200 |

end |

#### 11.3` `Data

##### 11.3.1` `Definitions

Wherever possible, provide annotations in Data definitions:

data Animal: |

| snake(name :: String) |

| dillo(weight :: Number, living :: Boolean) |

end |

##### 11.3.2` `Cases

cases (Animal) a: |

| snake(s) => s == "Dewey" |

| dillo(w, l) => (w < 10) and l |

end |

cases (Animal) a: |

| snake(s) => ... |

| dillo(w, _) => ... |

end |

cases (Animal) a: |

| snake(s) => ... |

| dillo(dummy, dummy) => ... |

end |

cases (Animal) a: |

| snake(s) => ... |

| dillo(_, _) => ... |

end |

cases (Animal) a: |

| snake(s) => ... |

| dillo(_, _) => raise("Serpents only, please!") |

end |

#### 11.4` `Naming Intermediate Expressions

##### 11.4.1` `Local Variables

fun hypo-len(a, b): |

num-sqrt((a * a) + (b * b)) |

end |

fun hypo-len(a, b): |

a2 = a * a |

b2 = b * b |

sum-of-other-two-sides = a2 + b2 |

num-sqrt(sum-of-other-two-sides) |

end |

##### 11.4.2` `Beware of var!

fun hypo-len(a, b): |

var a2 = a * a |

var b2 = b * b |

var sum-of-other-two-sides = a2 + b2 |

num-sqrt(sum-of-other-two-sides) |

end |