added best practice for style guides

Author: thomasWeise

bookbase

@@ -95,8 +95,8 @@
 
 We can change~\pythonil{cpy} by deleting its first element via~\pythonil{del cpy[0]}.
 \pythonil{numbers} will be unaffected by this and stays unchanged.
-Now, both \pythonil{cpy == numbers} and \pythonil{cpy is numbers}\pythonIdx{is} will be~\pythonil{False}.
-By the way, in the same manner as \pythonil{not in} is the opposite of the \pythonil{in}~operator, \pythonilIdx{not is} is the opposite of~\pythonilIdx{is}:
+Now, both \pythonil{cpy == numbers}\pythonIdx{==} and \pythonil{cpy is numbers}\pythonIdx{is} will be~\pythonil{False}.
+By the way, in the same manner as \pythonilIdx{not in} is the opposite of the \pythonil{in}~operator, \pythonilIdx{not is} is the opposite of~\pythonilIdx{is}:
 \pythonil{cpy is not numbers} yields \pythonil{True} because \pythonil{cpy} is not the same object as \pythonil{numbers}.
 
 In \cref{lst:lists:lists_3}, we continue our journey through the magical land of \python\ \pythonils{list}.
@@ -109,7 +109,7 @@
 In \cref{sec:strBasicOperations}, we discussed string slicing.
 Lists can be sliced in pretty much the same way\pythonIdx{list!slicing}\pythonIdx{slicing}\pythonIdx{slice}~\cite{PSF:P3D:TPLR:S}.
 When slicing a list~\pythonil{l} or a string, you can provide either two or three values in the square brackets\pythonIdx{[\idxdots]}\pythonIdx{[i:j:k]}, i.e., either do~\pythonil{l[i:j]}\pythonIdx{[i:j]}\pythonIdx{slicing} or \pythonil{l[i:j:k]}.
-If \pythonil{j < 0}, then it is replaced with~\pythonil{len(l) - j}.
+If \pythonil{j < 0}, then it is replaced with~\pythonil{len(l) - j}\pythonIdx{len}.
 In both the two and three indices case, \pythonil{i} is the inclusive start index and \pythonil{j} is the exclusive end index, i.e., all elements with index~\pythonil{m} such that \pythonil{i <= m < j}.
 In other words, the slice will contain elements from~\pythonil{l} whose index is between~\pythonil{i} and~\pythonil{j}, including the element at index~\pythonil{i} but \emph{not} including the element at index~\pythonil{j}.
 If a third index~\pythonil{k} is provided, the it is the step length.

text/main/basics/collections/lists/lists.tex

@@ -4,21 +4,21 @@
 We have also already learned our first two \python\ commands:%
 %
 \begin{itemize}%
-\item \pythonil{print("Hello World!")} prints the text \inQuotes{Hello World!} to the output.
-\item \pythonil{exit()} exits and terminates the \python\ interpreter.%
+\item \pythonil{print("Hello World!")}\pythonIdx{print} prints the text \inQuotes{Hello World!} to the output.
+\item \pythonil{exit()}\pythonIdx{exit} exits and terminates the \python\ interpreter.%
 \end{itemize}%
 %
 Now, it would be very strange if the \pythonil{print} function could print \inQuotes{Hello World!}.
 That would not make much sense.
-\pythonil{print} expects one parameter.
+\pythonilIdx{print} expects one parameter.
 This parameter cannot just be anything.
 It must be a text.
 
-The command \pythonil{exit}, on the other hand, can either have no parameter or one parameter.
+The command \pythonilIdx{exit}, on the other hand, can either have no parameter or one parameter.
 If it receives one parameter, this parameter will be the \pgls{exitCode} of the program.
 Here, \pythonil{0} indicates success.
 If no parameter is provided, this will be used as default value.
-We need to invoke \pythonil{exit} if we use the \python\ console in the \pgls{terminal} explicitly.
+We need to invoke \pythonilIdx{exit} if we use the \python\ console in the \pgls{terminal} explicitly.
 If we just run a program, then after the last instruction of the program was executed, then the interpreter will also terminate with \pgls{exitCode}~0.
 Indeed, when we executed our first program in \cref{sec:ourFirstProgram}, we saw exactly that happen in \cref{fig:firstProgram09programResult}.
 Different from the parameter of \pythonil{print}, which must be some text, the parameter of \pythonil{exit} needs to be a number.

text/main/basics/simpleDataTypesAndOperations/introduction/introduction.tex

@@ -157,6 +157,25 @@
 Variable names should be lowercase, with words separated by underscores~\cite{PEP8}.%
 }
 %
+We now have seen some best practices on styling our code, e.g., \cref{bp:variableNames,bp:longstrDoubleQuote,bp:comments}, and many more such best practices will follow.
+Before continuing further, let us revisit the deeper meaning behind them.
+Why is it important to style our code in a consistent way?
+Why can't we just write things down in any way that pleases us?%
+%
+\bestPractice{codeStyle}{%
+Regardless which programming language you are using, it is important to write code and scripts in a consistent style, to use a consistent naming scheme for all things that can be named, and to follow the generally established best practices and norms for that language.%
+}%
+For many programming languages, there exist comprehensive and clear style guides.
+Since we usually work collaboratively on larger projects, writing code in a consistent style is very important.
+Ideally, all collaborators can open a source code file and easily read and understand our code.
+If everybody writes code in different styles, maybe using different indentations or different naming conventions, reading code can become harder and even confusing.
+Therefore, style guides often tell us how to name things and how to structure code consistently.%
+%
+\bestPractice{PEP8}{%
+The most important style guide for the \python\ programming language is PEP8:~\citetitle{PEP8}~\cite{PEP8} at \citeurl{PEP8}. %
+\python\ code violating PEP8 is invalid \python code.%
+}%
+%
 \FloatBarrier%
 \endhsection%
 %
@@ -241,37 +260,37 @@
 \centering%
 %
 \subfloat[][%
-The file \textil{pi_liu_hui.py} opened in \pycharm.%
+The file \programUrl{variables:pi_liu_hui} opened in \pycharm.%
 \label{fig:liuHuiPiPyCharm1}%
 ]{%
 \tightbox{\includegraphics[width=0.49\linewidth]{\currentDir/liuHuiPiPyCharm1}}%
 }%
 \hfill%
 %
 \subfloat[][%
-Left-clicking on \menu{Run `pi\_liu\_hui'} in the pop-up menu after right-clicking on \textil{pi_liu_hui.py}, or directly pressing \keys{\ctrl+\shift+F10}, to run the program.%
+Left-clicking on \menu{Run `pi\_liu\_hui'} in the pop-up menu after right-clicking on \programUrl{variables:pi_liu_hui}, or directly pressing \keys{\ctrl+\shift+F10}, to run the program.%
 \label{fig:liuHuiPiPyCharm2}%
 ]{%
 \tightbox{\includegraphics[width=0.49\linewidth]{\currentDir/liuHuiPiPyCharm2}}%
 }%
 \\%
 %
 \subfloat[][%
-The output of the program \textil{pi_liu_hui.py} in \pycharm.%
+The output of the program \programUrl{variables:pi_liu_hui} in \pycharm.%
 \label{fig:liuHuiPiPyCharm3}%
 ]{%
 \tightbox{\includegraphics[width=0.7\linewidth]{\currentDir/liuHuiPiPyCharm3}}%
 }%
 \\%
 %
 \subfloat[][%
-The output of the program \textil{pi_liu_hui.py} in the \ubuntu\ \pgls{terminal} (which you can open via~\ubuntuTerminal).%
+The output of the program \programUrl{variables:pi_liu_hui} in the \ubuntu\ \pgls{terminal} (which you can open via~\ubuntuTerminal).%
 \label{fig:liuHuiPiTerminal}%
 ]{%
 \includegraphics[width=0.7\linewidth]{\currentDir/liuHuiPiTerminal}%
 }%
 %
-\caption{Running the program \textil{pi_liu_hui.py} from \cref{lst:variables:assignment} in \pycharm~(\cref{fig:assignmentPyCharm1,fig:assignmentPyCharm2,fig:assignmentPyCharm3}) or the \ubuntu\ \pgls{terminal}~(\cref{fig:assignmentTerminal}).}%
+\caption{Running the program \programUrl{variables:pi_liu_hui} from \cref{lst:variables:assignment} in \pycharm~(\cref{fig:assignmentPyCharm1,fig:assignmentPyCharm2,fig:assignmentPyCharm3}) or the \ubuntu\ \pgls{terminal}~(\cref{fig:assignmentTerminal}).}%
 \label{fig:variables:liuHuiPi}%
 \end{figure}%
 %