HOL-OCL
/
su4sml
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Improved markdown.

This commit is contained in:
Achim D. Brucker 2016-10-14 00:10:06 +01:00
parent 173c721611
commit d6601ee58d
1 changed files with 60 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
CodingStyle.md
View File

@ -1,13 +1,12 @@
# su4sml coding style # su4sml coding style
We here document coding-style guidelines that should be adhered to. We here document coding-style guidelines that should be adhered to.
Much of the existing code is not yet following these guidelines, Much of the existing code is not yet following these guidelines,
patches are welcome. This style-guide was inspired by the SML Style Guide patches are welcome. This style-guide was inspired by the SML Style
from Cornell university [1]. Guide from
[Cornell university](http://www.cs.cornell.edu/Courses/cs312/2007fa/handouts/style.htm).
## Chapter 1: Indentation and breaking long lines ## Chapter 1: Indentation and breaking long lines
The limit on the length of lines is 80 columns and this is a hard The limit on the length of lines is 80 columns and this is a hard
limit. Using more than 80 columns causes your code to wrap around to limit. Using more than 80 columns causes your code to wrap around to
the next line, which is devastating to readability. the next line, which is devastating to readability.
@ -55,18 +54,18 @@ of thought. The best way to transform code that constructs expressions over
multiple lines to something that has good style is to factor the code using a multiple lines to something that has good style is to factor the code using a
let expression. Consider the following: let expression. Consider the following:
Bad * Bad
```sml ```sml
fun euclid (m:int,n:int) : (int * int * int) = fun euclid (m:int,n:int) : (int * int * int) =
if n=0 if n=0
then (b 1, b 0, m) then (b 1, b 0, m)
else (#2 (euclid (n, m mod n)), u - (m div n) * else (#2 (euclid (n, m mod n)), u - (m div n) *
(euclid (n, m mod n)), #3 (euclid (n, m mod n))) (euclid (n, m mod n)), #3 (euclid (n, m mod n)))
``` ```
Better * Better
```sml ```sml
fun euclid (m:int,n:int) : (int * int * int) = fun euclid (m:int,n:int) : (int * int * int) =
if n=0 if n=0
then (b 1, b 0, m) then (b 1, b 0, m)
@ -75,9 +74,9 @@ Better
u - (m div n) * (euclid (n, m mod n)), u - (m div n) * (euclid (n, m mod n)),
#3 (euclid (n, m mod n))) #3 (euclid (n, m mod n)))
``` ```
Best * Best
```
fun euclid (m:int,n:int) : (int * int * int) = fun euclid (m:int,n:int) : (int * int * int) =
if n=0 if n=0
then (b 1, b 0, m) then (b 1, b 0, m)
@ -88,38 +87,39 @@ Best
in in
(v, u - q*v, g) (v, u - q*v, g)
end end
```
Do not factor unnecessarily. Do not factor unnecessarily.
Bad * Bad
```sml ```sml
let let
val x = TextIO.inputLine TextIO.stdIn val x = TextIO.inputLine TextIO.stdIn
in in
case x of case x of
... ...
end end
``` ```
Good * Good
```sml ```sml
case TextIO.inputLine TextIO.stdIn of case TextIO.inputLine TextIO.stdIn of
... ...
``` ```
Bad (provided y is not a large expression): * Bad (provided y is not a large expression):
```sml ```sml
let val x = y*y in x+z end let val x = y*y in x+z end
``` ```
Good * Good
```sml ```sml
y*y + z y*y + z
``` ```
## Chapter 3: Comments ## Chapter 3: Comments
Comments should be written with
Comments should be written with SMLDoc [2] in mind; a, nightly updated, API [SMLDoc](http://www.pllab.riec.tohoku.ac.jp/smlsharp/?SMLDoc) in mind;
documentation is available [3]. For example: a, nightly updated, API documentation is
[available](http://projects.brucker.ch/su4sml/smldoc/). For example:
```sml ```sml
(** (**
* opens a file. * opens a file.
@ -256,8 +256,8 @@ Combine nested case Expressions. Rather than nest case expressions, you can
combine them by pattern matching against a tuple, provided the tests in the combine them by pattern matching against a tuple, provided the tests in the
case expressions are independent. Here is an example: case expressions are independent. Here is an example:
Bad * Bad
```sml ```sml
let let
val d = Date.fromTimeLocal(Time.now()) val d = Date.fromTimeLocal(Time.now())
in in
@ -272,11 +272,10 @@ Bad
10 => print "Happy Metric Day" 10 => print "Happy Metric Day"
| _ => ()) | _ => ())
end end
``` ```
* Good
Good ```sml
```sml
let let
val d = Date.fromTimeLocal(Time.now()) val d = Date.fromTimeLocal(Time.now())
in in
@ -286,37 +285,38 @@ Good
| (Date.Oct, 10) => print "Happy Metric Day" | (Date.Oct, 10) => print "Happy Metric Day"
| _ => () | _ => ()
end end
``` ```
Avoid the use valOf, hd, or tl. The functions valOf, hd, and tl are used to
deconstruct option types and list types. However, they raise exceptions on Avoid the use `valOf`, `hd`, or `tl`. The functions `valOf`, `hd`,
certain inputs. You should avoid these functions altogether. It is usually and `tl` are used to deconstruct option types and list types.
easy to achieve the same effect with pattern matching. If you cannot manage to However, they raise exceptions on certain inputs. You should avoid
avoid them, you should handle any exceptions that they might raise. these functions altogether. It is usually easy to achieve the same
effect with pattern matching. If you cannot manage to avoid them, you
should handle any exceptions that they might raise.
## Chapter 6: Naming and declarations ## Chapter 6: Naming and declarations
Naming Conventions. The best way to tell at a glance something about the type Naming Conventions. The best way to tell at a glance something about the type
of a variable is to use the standard SML naming conventions. The following are of a variable is to use the standard SML naming conventions. The following are
the preferred rules that are (more or less) followed by the SML basis and the preferred rules that are (more or less) followed by the SML basis and
SML/NJ libraries: SML/NJ libraries:
Token SML Naming Convention Token | SML Naming Convention
Variables Symbolic or initial lower case. Use embedded caps for multiword names. ------------- |:-------------------------------------------------------------------------
Example: `getItem` Variables | Symbolic or initial lower case. Use embedded caps for multiword names.
Functions Initial lower case. Use embedded caps for multiword names. | *Example:* `getItem`
Example: `nameOf` Functions | Initial lower case. Use embedded caps for multiword names.
Constructors Initial upper case. Use embedded caps for multiword names. Historic | *Example:* `nameOf`
exceptions are nil, true, and false. Rarely are symbolic names like :: used. Constructors | Initial upper case. Use embedded caps for multiword names. Historic exceptions are `nil`, `true`, and `false`. Rarely are symbolic names like `::` used.
Example: `Node`, `EmptyQueue` | *Example:* `Node`, `EmptyQueue`
Types All lower case. Use underscores for multiword names. Types | All lower case. Use underscores for multiword names.
Example: `priority_queue` | *Example:* `priority_queue`
Signatures All upper case. Use underscores for multiword names. Signatures | All upper case. Use underscores for multiword names.
Example: `PRIORITY_QUEUE` | *Example:* `PRIORITY_QUEUE`
Structures Initial upper case. Use embedded caps for multiword names. Structures | Initial upper case. Use embedded caps for multiword names.
Example: `PriorityQueue` | *Example:* `PriorityQueue`
Functors Same as structure convention, except Fn completes the name. Functors | Same as structure convention, except Fn completes the name.
Example: `PriorityQueueFn` | *Example:* `PriorityQueueFn`
These conventions are not enforced by the compiler, though violations of the These conventions are not enforced by the compiler, though violations of the
variable/constructor conventions ought to cause warning messages because of the variable/constructor conventions ought to cause warning messages because of the
@ -543,7 +543,8 @@ of the SML standard library.
## Appendix ## Appendix
### Appendix I: Machine-support ### Appendix I: Machine-support
The following elisp-snippet provides marginal support for this coding-style for The following elisp-snippet provides marginal support for this coding-style for
the sml-mode [4] of Emacs [5]: the [sml-mode](http://www.smlnj.org/doc/Emacs/sml-mode.html) of
[Emacs](http://www.gnu.org/software/emacs/).
```emacs ```emacs
(setq sml-indent-level 2) (setq sml-indent-level 2)
@ -554,9 +555,3 @@ the sml-mode [4] of Emacs [5]:
(setq sml-electric-semi-mode nil) (setq sml-electric-semi-mode nil)
``` ```
### Appendix II: References
1. http://www.cs.cornell.edu/Courses/cs312/2007fa/handouts/style.htm
2. SMLDoc. http://www.pllab.riec.tohoku.ac.jp/smlsharp/?SMLDoc
3. http://projects.brucker.ch/su4sml/smldoc/
4. http://www.smlnj.org/doc/Emacs/sml-mode.html
5. http://www.gnu.org/software/emacs/