10 Pyret Style Guide
Ahoy matey! Here be the style guide for Pyret. Follow me rules to find the hidden treasure, or walk the plank!
10.1 References
You can consult the nascent Pyret Reference Guide, and also peruse the language introduction. Note that the introduction sometimes falls behind slightly; if you find an inconsistency between it and the current implementation, please let us know!
10.2 General
10.2.1 Indentation
You should indent your code blocks using two spaces (not tabs).
10.2.2 Line Length
Try to keep the total length of your lines under 80 characters.
10.2.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. 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.
10.2.3.1 Naming Constants
MY-COUNT = 100 |
e = 2.7182 |
10.2.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 |
10.2.4 File Naming
Use .arr as the extension for Pyret files.
10.2.5 Test Blocks
check: |
1 + 1 is 2 |
1 + 1 is-not 0 |
end |
10.3 Functions
10.3.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.
10.3.2 Documentation Strings
fun insert(x, l): |
doc: "consumes sorted list l; returns it with x in the right place" |
... |
end |
10.3.3 Annotations
fun str-len(str :: String) -> Number: |
# ... |
end |
fun length(lst :: List<Any>) -> Number: |
# ... |
end |
fun non-negative(n :: Number) -> Bool: |
n >= 0 |
end |
fun sqrt(n :: Number%(non-negative)) -> Number: |
# ... |
end |
10.3.4 Testing
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 |
10.4 Data
10.4.1 Definitions
Wherever possible, provide annotations in Data definitions:
data Animal: |
| snake(name :: String) |
| dillo(weight :: Number, living :: Bool) |
end |
10.4.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 |