styleguide included here, as well

Author: martin-henz

doc/README.md

@@ -0,0 +1,16 @@
+Required for making the documents is a LaTeX installation.
+
+Just try
+	make
+in order to make the four documents
+source_1.pdf
+source_2.pdf
+source_3.pdf
+source_4.pdf
+source_styleguide.pdf
+
+If you get an error, try
+       touch *.tex
+and try
+       make
+again.

doc/source_styleguide.tex

@@ -0,0 +1,351 @@
+\input source_header.tex
+
+\begin{document}
+	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+	\docheader{beta release}{Source}{Style Guide}
+	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+This is the style guide for the language Source,
+the official language of the book \emph{Structure and Interpretation
+of Computer Programs}, JavaScript Adaptation.
+You have never heard of Source? No worries! It was invented
+it just for the purpose of the book. Source is a sublanguage of 
+\href{http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf}{
+ECMAScript 2016 ($7^{\textrm{th}}$ Edition)}. This style guide is a compilation
+of commonly accepted rules, with the possible exception of conditional expressions
+on page~\pageref{condex}.
+        
+\section*{Indentation}
+  Use a four space indent. This means that if a line $L$ ends with \verb#{#, then 
+the following line starts with four more spaces than required to reach the keyword
+\lstinline{function}, \lstinline{if} or \lstinline{else} in $L$.
+Example:
+\begin{lstlisting}
+function make_abs_adder(x) {
+    function the_adder(y) {
+        if (x >= 0) {
+            return x + y;
+        } else {
+            return -x + y;
+        }
+    }
+    return the_adder;
+}
+\end{lstlisting}
+Note the four spaces before \lstinline{return}, and then indentation of the \lstinline{if}
+statement four spaces to the right of the preceding \lstinline{function}.
+
+\section*{Line Length}
+  Lines should be truncated such that they do not require excessive horizontal scrolling.
+  As a guide, it should be \emph{no more than 80 characters}.
+  
+\section*{Curly Braces}
+  Curly braces should \emph{open on the same line and close on a new line}.
+  Statements within the curly braces should be indented one more level.
+
+\begin{lstlisting}
+// function declaration
+function my_function(<parameters>) {
+    <statements here should be indented>
+}
+
+// if-else
+if (<predicate>) {
+    ...
+} else if (<predicate>) {
+    ...
+} else {
+    ...
+}
+
+// nested-if
+if (<predicate>) {
+    ...
+    if (<some other predicate>) {
+        ...
+    }
+    ...
+}
+\end{lstlisting}
+
+\paragraph{Always use curly braces.} Even if the block consists of only 
+  one statement.
+  This is required in Source, and recommended in JavaScript.
+
+\begin{lstlisting}
+// correct Source
+if (<predicate>) {
+    return x + y;
+} else {
+    return x * y;
+}
+
+// incorrect Source
+if (<predicate>) 
+    return x + y;
+else 
+    return x * y;
+
+// worse
+if (<predicate>) return x + y;
+else return x * y;
+\end{lstlisting}
+
+\section*{Whitespace}
+
+  \subsection*{Operators}
+    Leave a single space between binary and ternary operators.
+	
+\begin{lstlisting}
+// good style
+const x = 1 + 1;
+
+// bad style
+const x=1+1;
+
+// good style
+return (x === 0) ? "zero" : "not zero";
+
+// bad style
+return (x === 0)?"zero":"not zero";
+\end{lstlisting}
+	
+	Do not leave a space between unary operators and the variable involved.
+
+\begin{lstlisting}
+// good style
+const negative_x = -x;
+
+// bad style
+const negative_x = - x;
+\end{lstlisting}
+
+\subsection*{Function Definitions}
+
+Keep the parameters and the body expression of a function definition expression
+in one line, if they are short enough.
+
+If they are lengthy, use
+indentation. The indentation starts just below the first character of the \textit{parameter},
+or the open parenthesis, if there are multiple parameters. If the body expression does not
+fit in one line, use indentation so that the subsequent lines start after the blank character
+after the arrow.
+
+\begin{lstlisting}
+// good style
+function count_buttons(garment) {
+    return accumulate((sleaves, total) => sleaves + total,
+                      0, 
+		      map(jacket
+		          => is_checkered(jacket)
+		             ? count_buttons(jacket)
+                             : 1,
+			  garment));
+}
+
+// bad style
+function count_buttons(garment) {
+    return accumulate((sleaves, total)
+                      =>
+                      sleaves + total,
+                      0, 
+		      map(jacket
+		          => is_checkered(jacket)
+		          ? count_buttons(jacket)
+                          : 1,
+			  garment));
+}
+
+
+\end{lstlisting}
+
+
+  \subsection*{Conditional Expressions}
+\label{condex}
+Keep the three components of a conditional expression in one line, if they are short enough.
+
+\begin{lstlisting}
+// good style
+const aspect_ratio = landscape ? 4 / 3 : 3 / 4;
+
+// bad style
+const aspect_ratio = landscape
+                   ? 4 / 3
+                   : 3 / 4;
+\end{lstlisting}
+
+If the \textit{consequent-expression} or \textit{alternative-expression} are lengthy, use
+indentation. The indentation starts just below the \textit{predicate}.
+
+\begin{lstlisting}
+// good style
+function A(x,y) {
+    return y === 0
+           ? 0
+           : x === 0
+             ? 2 * y
+             : y === 1
+               ? 2
+               : A(x - 1, A(x, y - 1));
+
+// bad style
+function A(x,y) {
+    return y === 0 ? 0 : x === 0 ? 2 * y : y === 1 ? 2 : A(x - 1, A(x, y - 1));
+}
+
+// bad style
+function A(x,y) {
+    return y === 0
+               ? 0
+               : x === 0
+                     ? 2 * y
+                     : y === 1
+                           ? 2
+                           : A(x - 1, A(x, y - 1));
+}
+\end{lstlisting}
+
+  \subsection*{Conditional Statements and Functions}
+  Leave a single space between the \lstinline{if} statement and the first parenthesis and before every opening curly brace.
+  Start your \lstinline{else} statement on the same line as the closing curly brace, with a single space between them.
+
+\begin{lstlisting}
+if (<predicate>) {
+    ...
+} else if (<predicate>) {
+    ...
+} else {
+    ...
+}
+\end{lstlisting}
+
+  When calling or declaring a function with multiple parameters, leave a space after each comma.
+  There should also be no spaces before your parameter list.
+
+\begin{lstlisting}
+// good style
+function my_function(arg1, arg2, arg3) {
+    ...
+}
+
+// bad style
+function my_function (arg1, arg2, arg3) {
+    ...
+}
+
+// good style
+my_function(1, 2, 3);
+
+// bad style
+my_function(1,2,3);
+
+// bad style
+my_function (1, 2, 3);
+\end{lstlisting}
+
+  There should be no spaces after your opening parenthesis and before your closing parenthesis.
+  
+\begin{lstlisting}
+// bad style
+function my_function( arg1, arg2, arg3 ) {
+    ...
+}
+
+// bad style
+my_function( 1, 2, 3 );
+
+// bad style
+if ( x === 1 ) {
+    ...
+}
+
+// good style
+function my_function(arg1, arg2, arg3) {
+    ...
+}
+
+// good style
+my_function(1, 2, 3);
+
+// good style
+if (x === 1) {
+    ...
+}
+\end{lstlisting}
+
+  Clean up \emph{all trailing whitespace} before submitting your program.
+
+\section*{Variables}
+\subsection*{Naming}
+When naming variables, use \emph{underscores} to separate words. Examples: \lstinline{my_variable}, \lstinline{x}, \lstinline{rcross_bb}.
+
+\subsection*{Nesting}
+Do not use the same variable name for nested scope. Examples:
+\begin{lstlisting}
+// bad program
+const x = 1;
+function f(x) {
+    // here, the name x declared using const
+    // is ``shadowed'' by the formal parameter x
+    ...
+}
+\end{lstlisting}
+
+\begin{lstlisting}
+// another bad program
+function f(x) {
+    return x => ...;
+    // here, the formal parameter x of f is ``shadowed'' 
+    // by the formal parameter of the returned function
+}
+\end{lstlisting}
+
+\begin{lstlisting}
+// a third bad program
+function f(x) {
+    const x = 1;
+    // in the following, the formal parameter x of f
+    // is ``shadowed'' by the const declaration of x.
+    ...
+}
+\end{lstlisting}
+Finally, the worst case would be a (surely accidental) 
+use of the same variable name for two parameters of a function.
+In this case, the second variable is not visible; it is ``shadowed''
+by the first.
+\begin{lstlisting}
+// worse than the above
+function f(x, x) {
+    ...
+}
+\end{lstlisting}
+
+\section*{Comments}
+Comments should be used to describe and explain statements 
+that might not be obvious to a reader.
+Redundant comments should be avoided. The comment in the following program is useful
+because it explains what \lstinline{x} and \lstinline{y} stands for and what type of
+object is meant. 
+\begin{lstlisting}
+// area of rectangle with sides x and y
+function area(x, y) {
+    return x * y;
+}
+\end{lstlisting}
+The programmer has decided to use the short word \lstinline{area} as the name of the function,
+which is ok, as long as it is clear that the geometric objects that the program deals with
+are always rectangles.
+
+An example for bad style as a result of a redundant comment follows here:
+\begin{lstlisting}
+// square computes the square of the argument x
+function square(x) {
+    return x * x;
+}
+\end{lstlisting}
+%
+For multi-line comments, use \lstinline{/* ... */} and for single line comments, use \lstinline{//}.
+
+\end{document}
+
+