From 9b8815dddba3769992d380b5f3ec9dba434f5a77 Mon Sep 17 00:00:00 2001 From: Martin Henz Date: Tue, 28 Aug 2018 17:07:49 +0800 Subject: [PATCH] regularizes the style guide --- doc/source_styleguide.tex | 117 +++++++++++++++++++++++++------------- 1 file changed, 78 insertions(+), 39 deletions(-) diff --git a/doc/source_styleguide.tex b/doc/source_styleguide.tex index 644a28188..bd3302477 100644 --- a/doc/source_styleguide.tex +++ b/doc/source_styleguide.tex @@ -2,7 +2,7 @@ \begin{document} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - \docheader{beta release}{Source}{Style Guide} + \docheader{Version 1.0}{Source}{Style Guide} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This is the style guide for the language Source, @@ -35,6 +35,17 @@ \section*{Indentation} 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}. +Four space indent also applies when individual lines get too long and +need to be broken at convenient places. Example: +\begin{lstlisting} +function frac_sum(a, b) { + return (a > b) ? 0 + : 1 / (a * (a + 2)) + + + frac_sum(a + 4, b); +} +\end{lstlisting} + \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}. @@ -104,10 +115,10 @@ \section*{Whitespace} const x=1+1; // good style -return (x === 0) ? "zero" : "not zero"; +return x === 0 ? "zero" : "not zero"; // bad style -return (x === 0)?"zero":"not zero"; +return x === 0?"zero":"not zero"; \end{lstlisting} Do not leave a space between unary operators and the variable involved. @@ -120,43 +131,68 @@ \section*{Whitespace} const negative_x = - x; \end{lstlisting} -\subsection*{Function Definitions} +\subsection*{Function Definition Expressions} 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. +indentation. The indentation starts four characters after first character of +the \textit{parameter}, if there is only one, +or four characters after the open parenthesis, +if there are multiple parameters. If the body expression does not +fit in one line, use indentation following the first line of the body +expression. \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)); + 0, + map(jacket => + is_checkered(jacket) + ? count_buttons(jacket) + : 1, + garment)); } -// bad style +// good style +function count_buttons(garment) { + return accumulate( + (sleaves, total) => + delicate_calculation(sleaves + total), + 0, + map(jacket => + is_checkered(jacket) + ? count_buttons(jacket) + : 1, + garment)); +} + +// bad style: too much indentation function count_buttons(garment) { - return accumulate((sleaves, total) - => - sleaves + total, + return accumulate((sleaves, total) => + delicate_calculation(sleaves + total), 0, - map(jacket - => is_checkered(jacket) - ? count_buttons(jacket) + map(jacket => + is_checkered(jacket) + ? count_buttons(jacket) : 1, - garment)); + garment)); } - +// no newline allowed between parameters and => +function count_buttons(garment) { + return accumulate( + (sleaves, total) + => delicate_calculation(sleaves + total), + 0, + map(jacket + => is_checkered(jacket) + ? count_buttons(jacket) + : 1, + garment)); +} \end{lstlisting} @@ -170,30 +206,31 @@ \subsection*{Function Definitions} // bad style const aspect_ratio = landscape - ? 4 / 3 - : 3 / 4; + ? 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}. +indentation. The indentation is as usual four characters longer +than the indentation of the previous line. \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 + ? 0 + : x === 0 + ? 2 * y + : y === 1 + ? 2 + : A(x - 1, A(x, y - 1)); + +// bad style: line too long function A(x,y) { return y === 0 ? 0 : x === 0 ? 2 * y : y === 1 ? 2 : A(x - 1, A(x, y - 1)); } -// bad style +// bad style: too much indentation function A(x,y) { return y === 0 ? 0 @@ -275,12 +312,14 @@ \subsection*{Function Definitions} 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}. +\section*{Names} +\subsection*{Choice of names} +When naming constants or 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: +Do not use the same name for nested scope. Examples: \begin{lstlisting} // bad program const x = 1;