From 6a77370cc19633591a4f0d8203e5865e4ae109a4 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Mon, 27 May 2024 11:41:51 +0200 Subject: [PATCH 01/12] WIP on refactoring based on variation theory --- whatis/whatis.nw | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/whatis/whatis.nw b/whatis/whatis.nw index b1adc02..c94604d 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -129,6 +129,7 @@ programming: other methodologies. This means that we want to introduce other methodologies and show variation in these two aspects. + This is what \cref{RelatedApproaches} is for. }% So we can summarize the goals of literate programming as follows: \begin{itemize} @@ -156,10 +157,19 @@ But Knuth is convinced that this works well: methodology encourages me to do a better job.% } -\subsection{Related approaches} +\subsection{Related approaches}\label{RelatedApproaches} Let's start by thinking of systems that we know that might fulfil some of these goals. +\ltnote{% + As mentioned above, we want to show how well different methods do and don't + fulfil the goals of literate programming. + This is to get a better understanding for the goals themselves, rather than + the different methods. + + From a variation theoretic perspective, the students must see examples that + both fulfils and don't fulfil the goals. +}% \ltnote{% The purpose of \cref{NameOtherRelated} is to get them to think about systems they already know that might come close to this. From 1547f01e118b0d40891ed5dbeb721d614d93ceab Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:15:21 +0200 Subject: [PATCH 02/12] Updates makefiles to not use -halt-on-error --- makefiles | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makefiles b/makefiles index 513a170..e2b4c62 160000 --- a/makefiles +++ b/makefiles @@ -1 +1 @@ -Subproject commit 513a1702a1b8411d33033922ea66676b16e69cff +Subproject commit e2b4c62e3651d9ae205e5610e2e8b51c031fba92 From 5326e33c6afac7e43ab07fe9d91622f01e60b013 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:15:41 +0200 Subject: [PATCH 03/12] Updates references --- whatis/bibliography.bib | 111 ++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 44 deletions(-) diff --git a/whatis/bibliography.bib b/whatis/bibliography.bib index 1ec841f..f6e83a2 100644 --- a/whatis/bibliography.bib +++ b/whatis/bibliography.bib @@ -75,56 +75,79 @@ @book{Wolfram1988 } @book{KnuthAOCPvol3, - title = {The Art of Computer Programming: Sorting and Searching}, + title = {The Art of Computer Programming: Sorting and Searching}, author = {Knuth, Donald Ervin}, + edition = {2}, + isbn = {0-201-89685-0}, publisher = {Addison-Wesley}, - volume = {3}, - edition = {2}, - year = {1998}, - isbn = {0-201-89685-0}, + volume = {3}, + year = {1998}, } @article{Musser1997, - author = {Musser, David R.}, - title = {Introspective Sorting and Selection Algorithms}, - journal = {Software: Practice and Experience}, - volume = {27}, - number = {8}, - pages = {983-993}, - keywords = {quicksort, heapsort, sorting algorithms, introspective - algorithms, hybrid algorithms, generic algorithms, STL}, - doi = {https://doi.org/10.1002/(SICI)1097-024X(199708)27:8<983::AID-SPE117>3.0.CO;2-\#}, - abstract = {Abstract Quicksort is the preferred in-place sorting algorithm in - many contexts, since its average computing time on uniformly - distributed inputs is Θ(N log N), and it is in fact faster than - most other sorting algorithms on most inputs. Its drawback is - that its worst-case time bound is Θ(N2). Previous attempts to - protect against the worst case by improving the way quicksort - chooses pivot elements for partitioning have increased the - average computing time too much – one might as well use heapsort, - which has a Θ(N log N) worst-case time bound, but is on the - average 2–5 times slower than quicksort. A similar dilemma exists - with selection algorithms (for finding the i-th largest element) - based on partitioning. This paper describes a simple solution to - this dilemma: limit the depth of partitioning, and for - subproblems that exceed the limit switch to another algorithm - with a better worst-case bound. Using heapsort as the ‘stopper’ - yields a sorting algorithm that is just as fast as quicksort in - the average case, but also has an Θ(N log N) worst case time - bound. For selection, a hybrid of Hoare's FIND algorithm, which - is linear on average but quadratic in the worst case, and the - Blum–Floyd–Pratt–Rivest–Tarjan algorithm is as fast as Hoare's - algorithm in practice, yet has a linear worst-case time bound. - Also discussed are issues of implementing the new algorithms as - generic algorithms, and accurately measuring their performance in - the framework of the C+:+ Standard Template Library. ©1997 by - John Wiley \& Sons, Ltd.}, - year = {1997} + title = {Introspective Sorting and Selection Algorithms}, + author = {Musser, David R.}, + abstract = {Abstract Quicksort is the preferred in-place sorting algorithm in +many contexts, since its average computing time on uniformly +distributed inputs is Θ(N log N), and it is in fact faster than +most other sorting algorithms on most inputs. Its drawback is +that its worst-case time bound is Θ(N2). Previous attempts to +protect against the worst case by improving the way quicksort +chooses pivot elements for partitioning have increased the +average computing time too much – one might as well use heapsort, +which has a Θ(N log N) worst-case time bound, but is on the +average 2–5 times slower than quicksort. A similar dilemma exists +with selection algorithms (for finding the i-th largest element) +based on partitioning. This paper describes a simple solution to +this dilemma: limit the depth of partitioning, and for +subproblems that exceed the limit switch to another algorithm +with a better worst-case bound. Using heapsort as the ‘stopper’ +yields a sorting algorithm that is just as fast as quicksort in +the average case, but also has an Θ(N log N) worst case time +bound. For selection, a hybrid of Hoare's FIND algorithm, which +is linear on average but quadratic in the worst case, and the +Blum–Floyd–Pratt–Rivest–Tarjan algorithm is as fast as Hoare's +algorithm in practice, yet has a linear worst-case time bound. +Also discussed are issues of implementing the new algorithms as +generic algorithms, and accurately measuring their performance in +the framework of the C+:+ Standard Template Library. ©1997 by +John Wiley \& Sons, Ltd.}, + doi = {https://doi.org/10.1002/(SICI)1097-024X(199708)27:8<983::AID-SPE117>3.0.CO;2-\#}, + issn = {0038-0644}, + journal = {Software: Practice and Experience}, + keywords = {quicksort, heapsort, sorting algorithms, introspective +algorithms, hybrid algorithms, generic algorithms, STL}, + month = {8}, + number = {8}, + pages = {983-993}, + publisher = {Wiley}, + volume = {27}, + year = {1997}, } @book{ProgrammingPearls, - title = {Programming Pearls}, - author = {Jon Bentley}, - publisher = {Addison-Wesley}, - year = {1999}, + title = {Programming Pearls}, + author = {Jon Bentley}, + booktitle = {CACM}, + doi = {10.1145/32232.315727}, + publisher = {Addison-Wesley}, + url = {https://dl.acm.org/doi/pdf/10.1145/32232.315727}, + year = {1999}, +} + +@article{ErrorsOfTeX, + title = {The Errors of \TeX}, + author = {Knuth, Donald E.}, + year = {1989}, + issue_date = {July 1989}, + publisher = {John Wiley \& Sons, Inc.}, + address = {USA}, + volume = {19}, + number = {7}, + issn = {0038-0644}, + doi = {10.1002/spe.4380190702}, + journal = {Softw. Pract. Exper.}, + month = {7}, + pages = {607–685}, + numpages = {79} } From 04aed6e542c325870d4e114cb666793d052669c4 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:16:45 +0200 Subject: [PATCH 04/12] Adds overview of answer to LP question in intro --- whatis/preamble.tex | 1 + whatis/whatis.nw | 33 +++++++++++++++++++++++++-------- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/whatis/preamble.tex b/whatis/preamble.tex index 447fb1c..5ec09f0 100644 --- a/whatis/preamble.tex +++ b/whatis/preamble.tex @@ -1,6 +1,7 @@ \usepackage[utf8]{inputenc} \usepackage[swedish,british]{babel} \usepackage{float} +\usepackage[inline]{enumitem} \usepackage{noweb} \usepackage{booktabs} diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 6994fbf..86322c4 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -193,19 +193,29 @@ Name them. \end{activity} \end{frame} +We'll now cover a few such systems: +\ltnote{% + This provides a reasonable overview of some of the possible answers. + If they answered and know one of the them, they do get enough feedback. + If they don't, we'll go into the details of them in the following text. +}% +\begin{enumerate*}[label=(\arabic*)] +\item notebooks, +\item docstrings, +\item rubber-ducking or rubber-duck debugging, +\item pair programming, +\item documentation in version control systems, and +\item pseudocode. +\end{enumerate*} +There might be more than those that I cover here, but these are among the most +well-known ones. + \paragraph{Notebooks} Probably the first that comes to mind is the Jupyter notebook, see \cref{fig:jupyter}. -\begin{frame} -\ltnote{% - \Cref{AnalyseNotebooks} allows the students to compare notebooks to the goals - of literate programming. - This is the start of a generalization pattern: - we keep the goals invariant and vary the systems/tool/approach. - (We did get the contrast above, in \cref{WhatDoesLPMean}.) -}% +\begin{frame} \begin{activity}\label{AnalyseNotebooks} How well do you know the concept of notebooks\footnote{% Be it Jupyter, Google Colab, or any other similar system. @@ -256,6 +266,13 @@ variables). \end{frame} \begin{frame} +\ltnote{% + \Cref{AnalyseNotebooks} allows the students to compare notebooks to the goals + of literate programming. + This is the start of a generalization pattern: + we keep the goals invariant and vary the systems/tool/approach. + (We did get the contrast above, in \cref{WhatDoesLPMean}.) +}% \only{\LPgoals} \begin{activity} How well do you think notebooks fulfil the goals of literate programming? From de913a6312b63e3c4c1d9e8691832b5bc6223e88 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:17:34 +0200 Subject: [PATCH 05/12] Moves the section on famous literate programs --- whatis/whatis.nw | 144 ++++++++++++++++++++++++++--------------------- 1 file changed, 80 insertions(+), 64 deletions(-) diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 86322c4..f20c99b 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -157,10 +157,89 @@ But Knuth is convinced that this works well: methodology encourages me to do a better job.% } +\softclearmargin + +\paragraph{Famous literate programs} + +\ltnote{% + It will probably be better for the motivation to hear about some famous + examples of literate programs---that they wouldn't know were literate + programs. + This surprise effect might have slightly deterring effect on sleepiness. +}% +The first program that comes to mind is of course +\begin{frame}% +\only{\centering\Huge}% +\TeX\autocite[this is in fact the literate source code of the program and a +published book]{TeXprogram} +and, based on that, +\LaTeX\footnote{\url{https://latex-project.org}}% +\end{frame}. +\TeX{} was of course among the first literate programs to be written. + +\Citeauthor{ErrorsOfTeX} goes quite into the details of the development of +\TeX{} in \citetitle{ErrorsOfTeX}\autocite{ErrorsOfTeX}. +This text might be of interest to students as it shows that everyone suffers +from making mistakes and that it might take days to debug errors for anyone. + +\begin{frame} + On 8th January 2014, Matt Pharr, Greg Humphreys, and Pat Hanrahan were + awarded the 2013 Scientific and Technical Academy Award for Physically Based + Rendering\autocite[][award for an earlier edition]{PBR}. + \begin{onlyenv}
+ See \cref{fig:pbr}. + The motivation: + \blockquote{% + Physically based rendering has transformed computer graphics lighting by + more accurately simulating materials and lights, allowing digital artists + to focus on cinematography rather than the intricacies of rendering. + First published in 2004, Physically Based Rendering is both a textbook + and a complete source-code implementation that has provided a widely + adopted practical roadmap for most physically based shading and lighting + systems used in film production. + } + \end{onlyenv} + + \begin{figure} + \begin{subfigure}{0.48\columnwidth} + \includegraphics[width=\columnwidth]{figs/pbrcover.jpg} + \caption{The cover of the book \citetitle{PBR}.} + \end{subfigure} + \begin{subfigure}{0.48\columnwidth} + \includegraphics[width=\columnwidth]{figs/pbr-authors-academy.jpg} + \caption{\Citeauthor{PBR} at the Academy Awards ceremony.} + \end{subfigure} + \caption{\label{fig:pbr}The book \citetitle{PBR} and its authors.} + \end{figure} +\end{frame} + +Knuth said of this: \blockquote{This book has deservedly won an Academy Award. +I believe it should also be nominated for a Pulitzer Prize.} +This book is a literate program. +%See \cref{fig:pbrlit} for an excerpt from the book. +%By the end of this text we'll be better equipped to read that text. +% +%\begin{frame} +% \begin{figure} +% \centering +% \includegraphics[width=\columnwidth]{figs/pbr.png} +% \caption{\label{fig:pbrlit}% +% An excerpt from the book \citetitle{PBR} (online version). +% } +% \end{figure} +%\end{frame} + +\begin{onlyenv} +\begin{frame} + Whatever Daniel wrote during the last decade \dots +\end{frame} +\end{onlyenv} + + \subsection{Related approaches}\label{RelatedApproaches} Let's start by thinking of systems that we know that might fulfil some of these -goals. +goals.% \ltnote{% As mentioned above, we want to show how well different methods do and don't fulfil the goals of literate programming. @@ -939,69 +1018,6 @@ Knuth's \cweb (what you see in \cref{web}), but not for \noweb. \end{frame} -\section{Famous literate programs} - -The first program that comes to mind is of course -\begin{frame}% -\only{\centering\Huge}% -\TeX\autocite{TeXprogram} -and -\LaTeX\footnote{\url{https://latex-project.org}}% -\end{frame}. -\TeX{} was of course among the first literate programs to be written. - -\begin{frame} - On 8th January 2014, Matt Pharr, Greg Humphreys, and Pat Hanrahan were - awarded the 2013 Scientific and Technical Academy Award for Physically Based - Rendering\autocite[][award for an earlier edition]{PBR}. - \begin{onlyenv}
- See \cref{fig:pbr}. - The motivation: - \blockquote{% - Physically based rendering has transformed computer graphics lighting by - more accurately simulating materials and lights, allowing digital artists - to focus on cinematography rather than the intricacies of rendering. - First published in 2004, Physically Based Rendering is both a textbook - and a complete source-code implementation that has provided a widely - adopted practical roadmap for most physically based shading and lighting - systems used in film production. - } - \end{onlyenv} - - \begin{figure} - \begin{subfigure}{0.48\columnwidth} - \includegraphics[width=\columnwidth]{figs/pbrcover.jpg} - \caption{The cover of the book \citetitle{PBR}.} - \end{subfigure} - \begin{subfigure}{0.48\columnwidth} - \includegraphics[width=\columnwidth]{figs/pbr-authors-academy.jpg} - \caption{\Citeauthor{PBR} at the Academy Awards ceremony.} - \end{subfigure} - \caption{\label{fig:pbr}The book \citetitle{PBR} and its authors.} - \end{figure} -\end{frame} - -Knuth said of this: \blockquote{This book has deservedly won an Academy Award. -I believe it should also be nominated for a Pulitzer Prize.} -This book is a literate program. -See \cref{fig:pbrlit} for an excerpt from the book. - -\begin{frame} - \begin{figure} - \centering - \includegraphics[width=\columnwidth]{figs/pbr.png} - \caption{\label{fig:pbrlit}% - An excerpt from the book \citetitle{PBR} (online version). - } - \end{figure} -\end{frame} - -\begin{onlyenv} -\begin{frame} - Whatever Daniel wrote during the last decade \dots -\end{frame} -\end{onlyenv} - \begin{frame} \printbibliography{} From 9b7e777f06e4eaeef42908c37c89f49e8a5679c2 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:18:08 +0200 Subject: [PATCH 06/12] Fixes spelling error and figure placement --- whatis/whatis.nw | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/whatis/whatis.nw b/whatis/whatis.nw index f20c99b..9792394 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -313,12 +313,12 @@ The code cells can be executed in any order, which is both a strength and a weakness. It's a strength because you can experiment and try things out. It's a weakness because you can't really successively build the program. -However, if they weren't independet, we would get dependencies and the cells +However, if they weren't independent, we would get dependencies and the cells would have to be executed in the right order (spaghetti code with global variables). \begin{frame} -\begin{figure} +\begin{figure}[b] \includegraphics[width=\columnwidth]{figs/jupyter-notebook.png} \caption{\label{fig:jupyter}% The Jupyter notebook. From e26d60e42f1bbd5311c8133b889cc67c3126b72b Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Wed, 24 Jul 2024 21:36:35 +0200 Subject: [PATCH 07/12] Minor improvements to first chapter --- whatis/whatis.nw | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 9792394..7cab2f9 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -346,14 +346,14 @@ variables). \begin{frame} \ltnote{% - \Cref{AnalyseNotebooks} allows the students to compare notebooks to the goals - of literate programming. + \Cref{NotebooksFullfilGoals} allows the students to compare notebooks to the + goals of literate programming. This is the start of a generalization pattern: we keep the goals invariant and vary the systems/tool/approach. (We did get the contrast above, in \cref{WhatDoesLPMean}.) }% \only{\LPgoals} -\begin{activity} +\begin{activity}\label{NotebooksFullfilGoals} How well do you think notebooks fulfil the goals of literate programming? \end{activity} \end{frame} @@ -397,9 +397,7 @@ without having to know how they do it. Consider the documentation for the function [[sorted]]\label{sortedDocExample} in Python: \begin{pycode} -print(r"\begin{verbatim}") -help(sorted) -print(r"\end{verbatim}") +didactic_pydoc("sorted", builtin=True) \end{pycode} Nothing in the documentation explains how the sorting is done, no details of the underlying sorting algorithm(s). @@ -455,6 +453,13 @@ programming? \end{activity} \end{frame} +This for sure comes close to the goals of literate programming. +However, none is documented, so it's lost to others\footnote{% + And your future self. +}. +Also, the programmer is not forced to explain things unless there is a bug to +find. + \begin{frame} \begin{uncoverenv}<1> \begin{block}{Rubber duck debugging} @@ -479,13 +484,6 @@ programming? \end{onlyenv} \end{frame} -This for sure comes close to the goals of literate programming. -However, none is documented, so it's lost to others\footnote{% - And your future self. -}. -Also, the programmer is not forced to explain things unless there is a bug to -find. - \paragraph{Pair programming} Pair programming is similar to rubber duck debugging, but with another human @@ -780,7 +778,9 @@ perspective) order, the code is extracted in the right order in \cref{foo.bar}. We can extract the documentation by weaving: [[noweave -n -latex foo.nw > foo.tex]]. This yields: -\inputminted{latex}{foo.tex} +\begin{fullwidth} +\inputminted[breaklines]{latex}{foo.tex} +\end{fullwidth} \begin{onlyenv}
Compiled into a document, it looks like this: \input{foo.tex} From a327f22de07645f7d59702235f5a06c7192b1f30 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Sat, 27 Jul 2024 13:30:54 +0200 Subject: [PATCH 08/12] Adds summary for each related concept --- whatis/bibliography.bib | 7 ++ whatis/whatis.nw | 202 ++++++++++++++++++++++------------------ 2 files changed, 118 insertions(+), 91 deletions(-) diff --git a/whatis/bibliography.bib b/whatis/bibliography.bib index f6e83a2..280e201 100644 --- a/whatis/bibliography.bib +++ b/whatis/bibliography.bib @@ -151,3 +151,10 @@ @article{ErrorsOfTeX pages = {607–685}, numpages = {79} } + +@book{CleanCode, + title = {Clean Code: A Handbook of Agile Software Craftsmanship}, + author = {Robert C. Martin}, + publisher = {Prentice Hall}, + year = {2008}, +} diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 7cab2f9..2702ae5 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -289,23 +289,23 @@ We'll now cover a few such systems: There might be more than those that I cover here, but these are among the most well-known ones. -\paragraph{Notebooks} +\subsubsection{Notebooks} -Probably the first that comes to mind is the Jupyter notebook, -see \cref{fig:jupyter}. +Probably the first that comes to mind is the Jupyter notebook. +As you can see in \cref{fig:jupyter}, a notebook consists of text interspersed +by code that can be executed (usually to generate graphics). \begin{frame} \begin{activity}\label{AnalyseNotebooks} -How well do you know the concept of notebooks\footnote{% - Be it Jupyter, Google Colab, or any other similar system. -}? +How well do you know the concept of notebooks? +(Be it Jupyter, Google Colab, or any other similar system.) \end{activity} \end{frame} -Notebooks consists of cells, which can be of different types. +In more detail, notebooks consists of cells, which can be of different types. Some might be text and others are code. The code cells can be executed and the output is shown below the cell, in the -document. +document (this is what we see in \cref{fig:jupyter}. This way the author can explain the code in the text cells and then show the code in the code cells. @@ -313,9 +313,10 @@ The code cells can be executed in any order, which is both a strength and a weakness. It's a strength because you can experiment and try things out. It's a weakness because you can't really successively build the program. -However, if they weren't independent, we would get dependencies and the cells -would have to be executed in the right order (spaghetti code with global -variables). +In some configurations, however, they can build on each other. +However, in this case, we get dependencies and the cells must be executed in +the right order (if not chronologically, we get \enquote{spaghetti code} with +global variables). \begin{frame} \begin{figure}[b] @@ -351,6 +352,10 @@ variables). This is the start of a generalization pattern: we keep the goals invariant and vary the systems/tool/approach. (We did get the contrast above, in \cref{WhatDoesLPMean}.) + + However, to do this, we'd better explain briefly what the technology or + system actually is. + The reader might not know, or have only limited knowledge of it. }% \only{\LPgoals} \begin{activity}\label{NotebooksFullfilGoals} @@ -361,11 +366,12 @@ How well do you think notebooks fulfil the goals of literate programming? It for sure fulfils the first goal, \enquote{\LPexplain}. However, it doesn't necessarily fulfil the second goal, \enquote{\LPorder}. We can't really have any order we want, we must follow the order of execution -in the cells---which is ordered for the computer, not the human\footnote{% - Although, these might align at times, at other times they don't. -}. +in the cells---which is ordered for the computer, not the human. +(Although, these might align at times, but at other times they don't.) -\begin{frame} +So in summary, we have: + +\begin{frame} \begin{block}{Notebooks} \begin{itemize} \item[\(+\)] {\color{green!75!black}\LPexplain} @@ -374,14 +380,35 @@ in the cells---which is ordered for the computer, not the human\footnote{% \end{block} \begin{remark} - Code cells independent, code in order of the computer. + Code is in order of the computer. \end{remark} \end{frame} -\paragraph{Docstrings} +\subsubsection{Docstrings} Docstrings is another concept that has been argued is literate programming. The reasoning is that we generate documentation from the code. +Consider the documentation for the function [[sorted]]\label{sortedDocExample} +in Python: +\begin{frame}[fragile] +\begin{pycode} +didactic_pydoc("sorted", builtin=True) +\end{pycode} +\end{frame} +The documentation here is generated from the function's code: +\begin{frame}[fragile] +\begin{minted}{python} +def sorted(iterable, /, *, key=None, reverse=False): + """ + Return a new list containing all items from the iterable in ascending + order. + + A custom key function can be supplied to customize the sort order, and the + reverse flag can be set to request the result in descending order. + """ + ... +\end{minted} +\end{frame} \begin{frame} \only{\LPgoals} @@ -394,11 +421,7 @@ The docstrings aim at explaining how to use a particular function or class. It explains what the inputs and outputs are, but not how those are achieved. The purpose of them is to describe how to use these constructs as black boxes, without having to know how they do it. -Consider the documentation for the function [[sorted]]\label{sortedDocExample} -in Python: -\begin{pycode} -didactic_pydoc("sorted", builtin=True) -\end{pycode} + Nothing in the documentation explains how the sorting is done, no details of the underlying sorting algorithm(s). @@ -408,7 +431,9 @@ However, that only explains what the code does, same as reading the code itself. It doesn't explain the programmer's intent when writing the code. -\begin{frame} +In summary: + +\begin{frame} \begin{block}{Docstrings} \begin{itemize} \item[\(-\)] {\color{red}\LPexplain} @@ -421,16 +446,21 @@ It doesn't explain the programmer's intent when writing the code. \end{remark} \end{frame} -\paragraph{Rubber duck debugging} +\subsubsection{Rubber duck debugging} Another related concept is rubber duck debugging. -\begin{frame} +\begin{frame} \begin{activity} How well do you know rubber duck debugging? \end{activity} \end{frame} +The idea of rubber duck debugging is that you explain the code for a rubber +duck (or any other object or person that can't help you solve the problem). +Just by explaining, you get a better understanding of the code, which helps you +to find the bug more easily. + \begin{frame} \begin{block}{Rubber duck debugging} \begin{itemize} @@ -440,11 +470,6 @@ How well do you know rubber duck debugging? \end{block} \end{frame} -The idea of rubber duck debugging is that you explain the code for a rubber -duck. -In doing so, you get a better understanding of the code, which helps you to -find the bug. - \begin{frame} \only{\LPgoals} \begin{activity} @@ -453,90 +478,91 @@ programming? \end{activity} \end{frame} -This for sure comes close to the goals of literate programming. -However, none is documented, so it's lost to others\footnote{% - And your future self. -}. -Also, the programmer is not forced to explain things unless there is a bug to -find. +This for sure comes close to the goals of literate programming: +We explain the details of the code, why we've done the way we did and what we +expected. +We can also explain the code in the order we want, to fit the human +understanding rather than the computer's execution. \begin{frame} -\begin{uncoverenv}<1> \begin{block}{Rubber duck debugging} \begin{itemize} \item[\(+\)] {\color{green!75!black}\LPexplain} \item[\(+\)] {\color{green!75!black}\LPorder} \end{itemize} \end{block} -\end{uncoverenv} +\end{frame} -\begin{onlyenv}<2> -\begin{remark} - But none is documented, so it's lost to others. -\end{remark} +However, none of this is documented, so it's lost to others (and our future +selves). +And we do spend more time reading code than writing it, so this is quite a +loss: \blockcquote[p.~14]{CleanCode}{% + Indeed, the ratio of time spent reading vs.~writing is well over 10:1. + We are constantly reading old code as part of the effort to write new code. +}. +Also, the programmer is not encouraged to explain the details unless there is a +bug to find. -\begin{block}{Rubber duck debugging, end product} +\begin{frame} +\begin{block}{Rubber duck debugging} \begin{itemize} \item[\(-\)] {\color{red}\LPexplain} \item[\(-\)] {\color{red}\LPorder} \end{itemize} \end{block} -\end{onlyenv} +\begin{remark} + None is documented, so it's lost to others. +\end{remark} \end{frame} -\paragraph{Pair programming} +\subsubsection{Pair programming} Pair programming is similar to rubber duck debugging, but with another human instead of a rubber duck and you do this while developing---not just when debugging. +So that's an improvement. \begin{frame} -\begin{onlyenv}<1-2> \begin{block}{Pair programming} Pair programming is sort of the same, but with a fellow human instead of a rubber duck. \end{block} -\end{onlyenv} -\begin{uncoverenv}<2> \begin{block}{Pair programming} \begin{itemize} \item[\(+\)] {\color{green!75!black}\LPexplain} \item[\(\approx\)] {\color{orange}\LPorder} \end{itemize} \end{block} -\end{uncoverenv} +\end{frame} -\begin{onlyenv}<2> -\begin{remark} - They have to write the code in the order the computer understands it. -\end{remark} -\end{onlyenv} +The two programmers working together explain the thoughts of the design and +code to each other as they progress the development. +(To be exact there is a \enquote{navigator}, who explains to the +\enquote{driver}, who writes the code.) -\begin{onlyenv}<3> -\begin{remark} - But this is not necessarily documented, so it's lost to others. -\end{remark} +To some extent, they can do this in the order needed. +However, in the end, the code must be written in the order the computer +understands it. +And in the end, nothing from this process is necessarily stored as +documentation. +So it's again lost to others, including the programmers' future selves. -\begin{block}{Pair programming, end product} +\begin{frame} +\begin{block}{Pair programming} \begin{itemize} \item[\(-\)] {\color{red}\LPexplain} \item[\(-\)] {\color{red}\LPorder} \end{itemize} \end{block} -\end{onlyenv} -\end{frame} - -The two programmers working together explains the thoughts of the design and -code to each other as they progress the development. -To some extent, they can do this in the order needed. -However, in the end, the code must be written in the order the computer -understands it. -But in the end, nothing from this process is necessarily stored. -So it's again lost to others, including the programmers' future selves. +\begin{remark} + They have to write the code in the order the computer understands it. + And it's not necessarily documented, so it's lost to others. +\end{remark} +\end{frame} -\paragraph{Documentation in version management} +\subsubsection{Documentation in version management} We can also document meaning in the version management system, as commit messages and notes in issues and pull requests. @@ -550,7 +576,7 @@ goals of literate programming? \end{frame} The documentation of \emph{changes} in the version management system sure -contains good explanation of why the changes are needed. +contains good explanations of why the changes are needed. For instance, [[git blame]] and similar commands, allows us to see a motivation for each line of code. @@ -566,7 +592,7 @@ For those we are probably left with only the comments in the code. And in this case, the order of exposition is adapted for the computer rather than humans. -\begin{frame} +\begin{frame} \begin{block}{Documentation in version management} \begin{itemize} \item[\(\approx\)] {\color{orange}\LPexplain} @@ -575,14 +601,12 @@ than humans. \end{block} \begin{remark} - \begin{itemize} - \item Documents changes mostly, not first version. - \item Exposition in diffs. - \end{itemize} + Documents changes mostly, not first version. + Exposition in diffs. \end{remark} \end{frame} -\paragraph{Pseudocode} +\subsubsection{Pseudocode} The last one that we'll cover is pseudocode. @@ -604,35 +628,31 @@ However, it's not necessarily integrated with the code. And in the worst case, it's thrown away once there is an implementation. \begin{frame} -\begin{uncoverenv}<1> \begin{block}{Pseudocode} \begin{itemize} \item[\(+\)] {\color{green!75!black}\LPexplain} \item[\(+\)] {\color{green!75!black}\LPorder} \end{itemize} \end{block} -\end{uncoverenv} - -\begin{onlyenv}<2> -\begin{remark} - \begin{itemize} - \item But this is not necessarily kept in the documentation. - \item It's also not necessarily integrated with the code. - \end{itemize} -\end{remark} +\end{frame} -\begin{block}{Pseudocode, end product} +\begin{frame} +\begin{block}{Pseudocode} \begin{itemize} \item[\(\approx\)] {\color{orange}\LPexplain} \item[\(\approx\)] {\color{orange}\LPorder} \end{itemize} \end{block} -\end{onlyenv} + +\begin{remark} + But this is not necessarily kept in the documentation. + It's also not necessarily integrated with the code. +\end{remark} \end{frame} -%\paragraph{Testing} +%\subsubsection{Testing} -\paragraph{Others} +\subsubsection{Others} This covered only some of the related concepts. From 0ba33e1322389b5d4e2e35c454f5f1cd640fc84d Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Sat, 27 Jul 2024 15:21:37 +0200 Subject: [PATCH 09/12] Adds ref to CodeComplete, removes URLs from bibliography --- whatis/bibliography.bib | 16 ++++++++++------ whatis/whatis.nw | 3 ++- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/whatis/bibliography.bib b/whatis/bibliography.bib index 280e201..f744159 100644 --- a/whatis/bibliography.bib +++ b/whatis/bibliography.bib @@ -5,8 +5,7 @@ @book{NecessaryConditionsOfLearning isbn = {978-1317811947}, month = {6}, publisher = {Routledge}, - url = {https://doi.org/10.4324/9781315816876}, - year = {2014}, + year = {2014}, } @article{Knuth1984, @@ -19,8 +18,7 @@ @article{Knuth1984 number = {2}, pages = {97--111}, publisher = {Oxford University Press (OUP)}, - url = {https://academic.oup.com/comjnl/article-pdf/27/2/97/981657/270097.pdf}, - volume = {27}, + volume = {27}, year = {1984}, } @@ -51,8 +49,7 @@ @article{Ramsey1994 number = {5}, pages = {97--105}, publisher = {Institute of Electrical and Electronics Engineers (IEEE)}, - url = {https://doi.org/10.1109/52.311070}, - volume = {11}, + volume = {11}, year = {1994}, } @@ -158,3 +155,10 @@ @book{CleanCode publisher = {Prentice Hall}, year = {2008}, } + +@book{CodeComplete, + title={Code complete}, + author={McConnell, Steve}, + year={2004}, + publisher={Pearson Education}, +} diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 2702ae5..16fe7d4 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -624,7 +624,8 @@ We can vary the level of detail and the order of exposition to fit the human understanding. As something usually used in the design process, it helps with the understanding of the overall design. -However, it's not necessarily integrated with the code. +However, it's not necessarily integrated with the code\autocite[Unless we use +the methodology suggested by][Ch.~9]{CodeComplete}. And in the worst case, it's thrown away once there is an implementation. \begin{frame} From f04a309000407d82111c47f7fa403070fc031e25 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Fri, 16 Aug 2024 13:02:45 +0200 Subject: [PATCH 10/12] Updates didactic --- didactic | 2 +- whatis/.gitignore | 1 + whatis/notes.tex | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/didactic b/didactic index 09a1dcc..4bc4ef0 160000 --- a/didactic +++ b/didactic @@ -1 +1 @@ -Subproject commit 09a1dcc2a1ebd05fc4c57b2bbeb7bf387366eac6 +Subproject commit 4bc4ef0f482792c72e8e1fac8b6784257a219c90 diff --git a/whatis/.gitignore b/whatis/.gitignore index 62f12da..dcbabb4 100644 --- a/whatis/.gitignore +++ b/whatis/.gitignore @@ -15,3 +15,4 @@ __pycache__/ tests_Makefile didactic_output_* didactic_code_* +whatis.tex diff --git a/whatis/notes.tex b/whatis/notes.tex index a84855f..cf9f046 100644 --- a/whatis/notes.tex +++ b/whatis/notes.tex @@ -7,6 +7,7 @@ \input{preamble.tex} \noweboptions{longxref,breakcode} +%\chapterstyle{arthangnum} \usepackage[noamsthm,notheorems]{beamerarticle} %\setjobnamebeamerversion{slides} From 9cd983bc64e490ee1e51880ed259527c43152f70 Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Fri, 16 Aug 2024 13:04:53 +0200 Subject: [PATCH 11/12] Moves introsort --- whatis/introsort.nw | 18 +++++++++--------- whatis/whatis.nw | 26 +++++++++++++------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/whatis/introsort.nw b/whatis/introsort.nw index b5f9d3c..f24c045 100644 --- a/whatis/introsort.nw +++ b/whatis/introsort.nw @@ -63,7 +63,7 @@ We use [[from introsort import *]] to import all functions from the module, so that we can use them as we would in the same module. (This makes reading easier.) -\subsubsection{The sorting function: \texttt{sorted}} +\subsection{The sorting function: \texttt{sorted}} We want to implement the function [[sorted]]. \begin{frame}[fragile] @@ -157,7 +157,7 @@ import math @ \end{frame} -\subsubsection{The sorting algorithm: \texttt{intro\textunderscore sort}} +\subsection{The sorting algorithm: \texttt{intro\textunderscore sort}} We need a separate function for Intro Sort that we can call recursively and vary the [[max_depth]] parameter. @@ -214,7 +214,7 @@ def test_intro_sort_quick(): @ -\subsubsection{Using Quick Sort} +\subsection{Using Quick Sort} The case using Quick Sort is the simplest case. We simply calculate the pivot and call [[intro_sort]] recursively on the two @@ -533,7 +533,7 @@ def test_partition_one_element(): @ -\subsubsection{Controlling sorting behaviour} +\subsection{Controlling sorting behaviour} We want to be able to control the sorting behaviour. We noticed above that we added a keyword argument to the [[partition]] function @@ -589,7 +589,7 @@ def test_sorted_key_reverse(): \end{frame} -\subsubsection{Using Insertion Sort} +\subsection{Using Insertion Sort} \begin{frame}[fragile] <>= @@ -702,7 +702,7 @@ def test_insertion_sort_one_element(): @ -\subsubsection{Using Heap Sort} +\subsection{Using Heap Sort} \begin{frame}[fragile] <>= @@ -824,7 +824,7 @@ def test_heap_sort(): \end{frame} -\subsubsection{Docstrings and literate programming} +\subsection{Docstrings and literate programming} We see that despite using literate programming, we used docstrings. Let's have a look at the docstrings for the functions we've defined. @@ -841,7 +841,7 @@ The documentation we've written using literate programming targets someone who needs to understand our implementation---someone who needs answers to all the whys, the decisions we made while writing the code. -\subsubsection{The test file} +\subsection{The test file} The test file [[test_introsort.py]] looks like this after we've tangled it: \begin{frame}[fragile,allowframebreaks] @@ -849,7 +849,7 @@ The test file [[test_introsort.py]] looks like this after we've tangled it: \only
{\inputminted{python}{test_introsort.py}} \end{frame} -\subsubsection{Building the tests} +\subsection{Building the tests} Normally, the tests resides in a directory [[/tests]], not in [[/src]]. We'll still use that directory structure. diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 16fe7d4..5e50377 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -960,19 +960,6 @@ All in all, the script [[merge.sh]] looks like this after we've tangled it: \only
{\inputminted{bash}{merge.sh}} \end{frame} -\subsection{Example: Docstrings and testing in Python} - -We've briefly discussed how docstrings relate to literate programming. -Now we'll see that we still want to use docstrings even though we use literate -programming. -We still want to have those when we use the modules we've written as an API. -The literate documentation is rather targeted at the maintainers of the code, -not users. -(Although there can be some overlap and some parts of the literate -documentation for sure can be targeted at users.) - -\mode{\input{introsort.tex}} - \subsection{Summary} \ltnote{% @@ -1039,6 +1026,19 @@ Knuth's \cweb (what you see in \cref{web}), but not for \noweb. \end{frame} +\section{Docstrings and testing in Python} + +We've briefly discussed how docstrings relate to literate programming. +Now we'll see that we still want to use docstrings even though we use literate +programming. +We still want to have those when we use the modules we've written as an API. +The literate documentation is rather targeted at the maintainers of the code, +not users. +(Although there can be some overlap and some parts of the literate +documentation for sure can be targeted at users.) + +\mode{\input{introsort.tex}} + \begin{frame} \printbibliography{} From 40cf37a06ee117236e68ea56213a4a2f3ccadf7f Mon Sep 17 00:00:00 2001 From: Daniel Bosk Date: Fri, 16 Aug 2024 13:05:08 +0200 Subject: [PATCH 12/12] Fixes some minor typos --- whatis/whatis.nw | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/whatis/whatis.nw b/whatis/whatis.nw index 5e50377..3bbb41e 100644 --- a/whatis/whatis.nw +++ b/whatis/whatis.nw @@ -498,8 +498,8 @@ selves). And we do spend more time reading code than writing it, so this is quite a loss: \blockcquote[p.~14]{CleanCode}{% Indeed, the ratio of time spent reading vs.~writing is well over 10:1. - We are constantly reading old code as part of the effort to write new code. -}. + We are constantly reading old code as part of the effort to write new code.% +} Also, the programmer is not encouraged to explain the details unless there is a bug to find. @@ -624,8 +624,12 @@ We can vary the level of detail and the order of exposition to fit the human understanding. As something usually used in the design process, it helps with the understanding of the overall design. -However, it's not necessarily integrated with the code\autocite[Unless we use -the methodology suggested by][Ch.~9]{CodeComplete}. +However, it's not necessarily integrated with the code\footnote{% + Unless we use the methodology proposed by \textcite[Ch.~9]{CodeComplete}. + However, even then, we don't keep the order of exposition adapted to humans. + When we use the pseudocode as the comments of the code, the order is dictated + by the computer's understanding. +}. And in the worst case, it's thrown away once there is an implementation. \begin{frame}