author haftmann Fri, 03 Nov 2006 14:22:34 +0100 changeset 21148 3a64d58a9f49 parent 21147 737a94f047e3 child 21149 ee207b9b8bf5
first version of style guide
--- 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 *}

-\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.
+
+      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}
*}


--- 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}%
-\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.
+
+      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%
%