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.
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. 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 Test Blocks
check: |
1 + 1 is 2 |
1 + 1 is-not 0 |
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 |
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
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 |