summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorOri Bernstein <ori@eigenstate.org>2012-08-12 18:52:20 -0400
committerOri Bernstein <ori@eigenstate.org>2012-08-12 18:52:20 -0400
commit1b37b97c96f832dd5623e2361f8b389c3057153e (patch)
treefbcd59061e8cd062685a6121544bdca6065771e7 /doc
parented6aa9f6f11b6a20cd4b45cd8cee4c3cae71d7f0 (diff)
downloadmc-1b37b97c96f832dd5623e2361f8b389c3057153e.tar.gz
Start on style guide.
Diffstat (limited to 'doc')
-rw-r--r--doc/lang.txt53
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: