diff options
author | Ori Bernstein <ori@eigenstate.org> | 2012-08-12 18:52:20 -0400 |
---|---|---|
committer | Ori Bernstein <ori@eigenstate.org> | 2012-08-12 18:52:20 -0400 |
commit | 1b37b97c96f832dd5623e2361f8b389c3057153e (patch) | |
tree | fbcd59061e8cd062685a6121544bdca6065771e7 /doc/lang.txt | |
parent | ed6aa9f6f11b6a20cd4b45cd8cee4c3cae71d7f0 (diff) | |
download | mc-1b37b97c96f832dd5623e2361f8b389c3057153e.tar.gz |
Start on style guide.
Diffstat (limited to 'doc/lang.txt')
-rw-r--r-- | doc/lang.txt | 53 |
1 files changed, 53 insertions, 0 deletions
diff --git a/doc/lang.txt b/doc/lang.txt index a3da76f..6353275 100644 --- a/doc/lang.txt +++ b/doc/lang.txt @@ -696,6 +696,59 @@ TABLE OF CONTENTS: 6. STYLE GUIDE: + 6.1. Brevity: + + Myrddin is a simple language which aims to strip away abstraction when + possible, and it is not well served by overly abstract or bulky code. + The code written should be a readable description of an algorithm, + aimed at conveying the essential operations in a linear and + straightforward fasion. + + Write for humans, not machines. Write linearly, so that an algorithm + can be understood with minimal function-chasing. + + 6.2. Naming: + + Names should be brief and evocative. A good name serves as a reminder + to what the function does. For functions, a single verb is ideal. For + local variables, a single character might suffice. Compact notation + is simpler to read, typographically. + + Variables names should describe the value contained, and function + names should describe the value returned. + + Good: spawn(myfunc) + Bad: create_new_thread_starting_at_function(myfunc) + + The identifiers used for constant values are put in Initialcase. + Functions and types are in singleword style, although underscores are + occasionally necessary to specify additional information within + functions, due to the lack of overloading. + + Good: + type mytype = int + var myvar : mytype + const Myconst = 42 + union + `Tagone int + ;; + + Bad: + type MyType = int /* types are 'singleword' */ + const my_func = {;...} /* function names should avoid _ */ + const myconst /* constants start with Uppercase */ + union + `sometag /* tags start with uppercase */ + ;; + + Acceptable: + const length_mm = {;...} /* '_' disambiguates returned values. */ + cosnt length_cm = {;...} + + 6.3. Collections: + + + 7. STANDARD LIBRARY: 8. GRAMMAR: |