# HG changeset patch # User haftmann # Date 1162560154 -3600 # Node ID 3a64d58a9f492993cea183d9645af60c57271502 # Parent 737a94f047e35949a595bf8ec3e0cf050b26f314 first version of style guide diff -r 737a94f047e3 -r 3a64d58a9f49 doc-src/IsarImplementation/Thy/ML.thy --- a/doc-src/IsarImplementation/Thy/ML.thy Fri Nov 03 14:22:33 2006 +0100 +++ b/doc-src/IsarImplementation/Thy/ML.thy Fri Nov 03 14:22:34 2006 +0100 @@ -5,9 +5,89 @@ chapter {* Aesthetics of ML programming *} -text {* FIXME style guide, see also -\url{http://caml.inria.fr/resources/doc/guides/guidelines.en.html} and -\url{http://www.cs.cornell.edu/Courses/cs312/2003sp/handouts/style.htm} +text {* This style guide is loosely based on + \url{http://caml.inria.fr/resources/doc/guides/guidelines.en.html}. +% FIMXE \url{http://www.cs.cornell.edu/Courses/cs312/2003sp/handouts/style.htm} + + Like any style guide, it should not be interpreted dogmatically. + Instead, it forms a collection of recommendations which, + if obeyed, result in code that is not considered to be + obfuscated. In certain cases, derivations are encouraged, + as far as you know what you are doing. + + \begin{description} + + \item[fundamental law of programming] + Whenever writing code, keep in mind: A program is + written once, modified ten times, and read + 100 times. So simplify its writing, + always keep future modifications in mind, + and never jeopardize readability. Every second you hesitate + to spend on making your code more clear you will + have to spend ten times understanding what you have + written later on. + + \item[white space matters] + Treat white space in your code as if it determines + the meaning of code. + + \begin{itemize} + + \item The space bar is the easiest key to find on the keyboard, + press it as often as necessary. {\ttfamily 2 + 2} is better + than {\ttfamily 2+2}, likewise {\ttfamily f (x, y)} + better than {\ttfamily f(x,y)}. + + \item Restrict your lines to \emph{at most} 80 characters. + This will allow you to keep the beginning of a line + in view while watching its end. + + \item Ban tabs; they are a context-sensitive formatting + feature and likely to confuse anyone not using your + favourite editor. + + \item Get rid of trailing whitespace. Instead, do not + surpess a trailing newline at the end of your files. + + \item Choose a generally accepted style of indentation, + then use it systematically throughout the whole + application. An indentation of two spaces is appropriate. + Avoid dangling indentation. + + \end{itemize} + + \item[cut-and-paste succeeds over copy-and-paste] + \emph{Never} copy-and-paste code when programming. If you + need the same piece of code twice, introduce a + reasonable auxiliary function (if there is no + such function, very likely you got something wrong). + Any copy-and-paste will turn out to be painful + when something has to be changed or fixed later on. + + \item[comments] + are a device which requires careful thinking before using + it. The best comment for your code should be the code itself. + Prefer efforts to write clear, understandable code + over efforts to explain nasty code. + + \item[functional programming is based on functions] + Avoid ``constructivisms'', e.g. pass a table lookup function, + rather than an actual table with lookup in body. Accustom + your way of codeing to the level of expressiveness + a functional programming language is giving onto you. + + \item[tuples] + are often in the way. When there is no striking argument + to tuple function arguments, just write your function curried. + + \item[telling names] + Any name should tell its purpose as exactly as possible, + while keeping its length to the absolutely neccessary minimum. + Always give the same name to function arguments which + have the same meaning. Separate words by underscores + (``{\ttfamily int\_of\_string}'', not ``{\ttfamily intOfString}'') + + \end{description} *} diff -r 737a94f047e3 -r 3a64d58a9f49 doc-src/IsarImplementation/Thy/document/ML.tex --- a/doc-src/IsarImplementation/Thy/document/ML.tex Fri Nov 03 14:22:33 2006 +0100 +++ b/doc-src/IsarImplementation/Thy/document/ML.tex Fri Nov 03 14:22:34 2006 +0100 @@ -24,9 +24,89 @@ \isamarkuptrue% % \begin{isamarkuptext}% -FIXME style guide, see also -\url{http://caml.inria.fr/resources/doc/guides/guidelines.en.html} and -\url{http://www.cs.cornell.edu/Courses/cs312/2003sp/handouts/style.htm}% +This style guide is loosely based on + \url{http://caml.inria.fr/resources/doc/guides/guidelines.en.html}. +% FIMXE \url{http://www.cs.cornell.edu/Courses/cs312/2003sp/handouts/style.htm} + + Like any style guide, it should not be interpreted dogmatically. + Instead, it forms a collection of recommendations which, + if obeyed, result in code that is not considered to be + obfuscated. In certain cases, derivations are encouraged, + as far as you know what you are doing. + + \begin{description} + + \item[fundamental law of programming] + Whenever writing code, keep in mind: A program is + written once, modified ten times, and read + 100 times. So simplify its writing, + always keep future modifications in mind, + and never jeopardize readability. Every second you hesitate + to spend on making your code more clear you will + have to spend ten times understanding what you have + written later on. + + \item[white space matters] + Treat white space in your code as if it determines + the meaning of code. + + \begin{itemize} + + \item The space bar is the easiest key to find on the keyboard, + press it as often as necessary. {\ttfamily 2 + 2} is better + than {\ttfamily 2+2}, likewise {\ttfamily f (x, y)} + better than {\ttfamily f(x,y)}. + + \item Restrict your lines to \emph{at most} 80 characters. + This will allow you to keep the beginning of a line + in view while watching its end. + + \item Ban tabs; they are a context-sensitive formatting + feature and likely to confuse anyone not using your + favourite editor. + + \item Get rid of trailing whitespace. Instead, do not + surpess a trailing newline at the end of your files. + + \item Choose a generally accepted style of indentation, + then use it systematically throughout the whole + application. An indentation of two spaces is appropriate. + Avoid dangling indentation. + + \end{itemize} + + \item[cut-and-paste succeeds over copy-and-paste] + \emph{Never} copy-and-paste code when programming. If you + need the same piece of code twice, introduce a + reasonable auxiliary function (if there is no + such function, very likely you got something wrong). + Any copy-and-paste will turn out to be painful + when something has to be changed or fixed later on. + + \item[comments] + are a device which requires careful thinking before using + it. The best comment for your code should be the code itself. + Prefer efforts to write clear, understandable code + over efforts to explain nasty code. + + \item[functional programming is based on functions] + Avoid ``constructivisms'', e.g. pass a table lookup function, + rather than an actual table with lookup in body. Accustom + your way of codeing to the level of expressiveness + a functional programming language is giving onto you. + + \item[tuples] + are often in the way. When there is no striking argument + to tuple function arguments, just write your function curried. + + \item[telling names] + Any name should tell its purpose as exactly as possible, + while keeping its length to the absolutely neccessary minimum. + Always give the same name to function arguments which + have the same meaning. Separate words by underscores + (``{\ttfamily int\_of\_string}'', not ``{\ttfamily intOfString}'') + + \end{description}% \end{isamarkuptext}% \isamarkuptrue% %