Added section on comments

This commit is contained in:
Kenneth John Odle 2023-07-29 12:03:34 -04:00
parent f2e65649b9
commit 7e815335d2

View File

@ -88,6 +88,7 @@
% Make a Python Symbol like a LaTeX symbol % Make a Python Symbol like a LaTeX symbol
\newcommand\kpy{P{\scriptsize \raisebox{-0.4em}{\hspace{-0.16em}Y}}T{\scriptsize \raisebox{-0.3em}{h}}\hspace{-0.15em}\raisebox{0.4em}{o}\hspace{0.05em}\raisebox{-0.2em}N} \newcommand\kpy{P{\scriptsize \raisebox{-0.4em}{\hspace{-0.16em}Y}}T{\scriptsize \raisebox{-0.3em}{h}}\hspace{-0.15em}\raisebox{0.4em}{o}\hspace{0.05em}\raisebox{-0.2em}N}
% Additional options %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Additional options %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\raggedbottom \raggedbottom
@ -106,9 +107,11 @@
\maketitle \maketitle
\begin{abstract} \begin{abstract}
This document consists of notes on Python, gleaned from various sources. A list of references (often with commentary) follows. This document consists of notes on Python, gleaned from various sources. A list of references (often with commentary) follows.
The latest version of this document can be found at \kref{https://git.kjodle.net/kjodle/Notes-on-Python}{https://git.kjodle.net/kjodle/Notes-\\on-Python}. The latest version of this document can be found at \kref{https://git.kjodle.net/kjodle/Notes-on-Python}{https://git.kjodle.net/kjodle/Notes-\\on-Python}.
This document was typeset in \LaTeX{}.
\end{abstract} \end{abstract}
\tableofcontents \tableofcontents
@ -126,6 +129,18 @@
I won't bore you with details. If you have made enough effort to find this document, you are probably aware of the importance of the Python programming language. If not, however, I'll give a brief summary. I won't bore you with details. If you have made enough effort to find this document, you are probably aware of the importance of the Python programming language. If not, however, I'll give a brief summary.
Python is platform independent. It emphasizes a concise syntax that aids in code readability. It also supports multiple coding styles, such as functional, imperative, object-oriented, and procedural.
\paragraph{Functional} Every statement is a kind of math equation. Functional programming is good for use in parallel processing activities.
\paragraph{Imperative} Computations occur as changes to program state. This is most often used for manipulating data structures.
\paragraph{Object-Oriented} This programming style uses objects to model the real world. It isn't fully implemented in Python because Python doesn't support features like data hiding.
\paragraph{Procedural} Tasks proceed one step at a time. Most often used for iteration, sequencing, selection, and modularization. It is the simplest form of programming.
\bigskip
Many fields depend on \kpy\footnote{This is my attempt to produce a text symbol for Python, similar to \LaTeX{}. My thought is that it looks like a snake wriggling back and forth. Your mileage, of course, may (and probably will) vary. If you would like to use this in your own documents (why?) I have defined it as a macro, which you can obtain from the source code for this document. See the abstract for its location.} to process data. Many fields depend on \kpy\footnote{This is my attempt to produce a text symbol for Python, similar to \LaTeX{}. My thought is that it looks like a snake wriggling back and forth. Your mileage, of course, may (and probably will) vary. If you would like to use this in your own documents (why?) I have defined it as a macro, which you can obtain from the source code for this document. See the abstract for its location.} to process data.
Mueller\cite{mueller-jp:23} has many reasons why a knowledge of Python may be useful in a job search. \kpull{This is \textit{not} my favorite book.}{22mm} They were fairly accurate as of their publication (2023),but things change quickly, so a keyword search of your preferred job boards is always in order. Mueller\cite{mueller-jp:23} has many reasons why a knowledge of Python may be useful in a job search. \kpull{This is \textit{not} my favorite book.}{22mm} They were fairly accurate as of their publication (2023),but things change quickly, so a keyword search of your preferred job boards is always in order.
@ -134,6 +149,55 @@ Mueller\cite{mueller-jp:23} has many reasons why a knowledge of Python may be us
\subsection{Version 2 versus Version 3} \subsection{Version 2 versus Version 3}
\subsection{Comments in Python}
Python supports single line comments by adding a hashtag (\texttt{\#}) to the beginning of each line:
\begin{Verbatim}
# This line is a comment.
\end{Verbatim}
Mulitline comments are not directly supported by Python. However, you can surround groups of lines to be commented out by using three double quotations marks or three single quotations marks on the lines before and after them:
\begin{Verbatim}[frame=lines, framesep=3mm, breaklines=true, label=Multiline Comments]
"""
These lines
will be ignored by Python
"""
'''
These lines will also
be ignored by Python
'''
\end{Verbatim}
The main difference between single line comments and multiline comments is that single line comments do not get exported to reports, whereas multiline comments do. Again, this is because Python does not fully support multiline commenting.
\subsubsection{Uses of Comments}
Comments are highly useful when writing code and often underutilized or poorly utilized. It has been suggested\cite{denker-j} that
\begin{quote}
\rule{\linewidth}{0.5pt}
software = code + documentation
\vspace{-12pt}
\rule{\linewidth}{0.5pt}
\end{quote}
That documentation is both external (i.e., user manuals) and internal (i.e., comments). You can (and should) use comments to:
\begin{itemize}[noitemsep]
\item Remind yourself what the code does and why you wrote it.
\item Record who wrote the code in a multi-person project.
\item Tell others how to maintain the code.
\item Make your code accessible to other developers.
\item List ideas for future updates.
\item Document the sources you used to build the code.
\item Maintain a list of improvements you've made.
\end{itemize}
You can, of course, also use comments to prevent certain lines of code from executing, a practice known as ``commenting out''. This is useful when troubleshooting your code.
\kcole \kcole
\newpage \newpage
@ -153,6 +217,11 @@ Mueller\cite{mueller-jp:23} has many reasons why a knowledge of Python may be us
\kcolb \kcolb
\bibitem{denker-j}
Denker, John S.
``Suggestions for Writing Good Software''.\\
\kbib\kref{https://www.av8n.com/computer/htm/good-software.htm}{https://www.av8n.com/computer/htm/good-\\software.htm}.
\bibitem{mueller-jp:23} \bibitem{mueller-jp:23}
Mueller, John Paul. Mueller, John Paul.
\textit{Beginning Programming with Python for Dummies}. \textit{Beginning Programming with Python for Dummies}.
@ -167,6 +236,12 @@ Mueller\cite{mueller-jp:23} has many reasons why a knowledge of Python may be us
\kbib\kref{https://www.python.org/about/gettingstarted/}{https://www.python.org/about/\\gettingstarted/}\\ \kbib\kref{https://www.python.org/about/gettingstarted/}{https://www.python.org/about/\\gettingstarted/}\\
\kbib The official site of the Python Software Foundation. \kbib The official site of the Python Software Foundation.
\bibitem{pythonorg:blurb}
python.org.
``What is Python? Executive Summary'',\\
\kbib\kref{https://www.python.org/doc/essays/blurb/}{https://www.python.org/doc/essays/blurb/}\\
\kbib The official description of what Python is.
\kcole \kcole
\end{thebibliography} \end{thebibliography}