From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 9 Sep 2020 15:53:55 +0000 (-0600)
Subject: Mention Code Complete as a resource.
X-Git-Tag: v9.3.0-rc1~1099^2~2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b1e78fbe30ccc9543db80c46b5d8d34d3fa02fa1;p=dealii.git

Mention Code Complete as a resource.
---

diff --git a/examples/step-1/doc/intro.dox b/examples/step-1/doc/intro.dox
index 1f1e353ddd..3a78ecedbb 100644
--- a/examples/step-1/doc/intro.dox
+++ b/examples/step-1/doc/intro.dox
@@ -185,6 +185,15 @@ are worthwhile browsing through before you start any large-scale programming:
   do I debug scientific computing codes?" or "Can I train myself to write code
   that has fewer bugs?".
 
+- You will benefit from becoming a better programmer. An excellent
+  resource to this end is the book "<a
+  href="https://en.wikipedia.org/wiki/Code_Complete">Code
+  Complete</a>" by Steve McConnell (ISBN 978-0735619678). It's already
+  a few years old, with the last edition published in 2004, but it has
+  lost none of its appeal as a guide to good programming practices,
+  and some of the principal developers use it as a group reading
+  project with every generation of their research group members.
+
 - The <a href="http://software-carpentry.org/">Software Carpentry project</a>
   that provides introductions to many topics that are important to dealing
   with software, such as version control, make files, testing, etc. It is
diff --git a/examples/step-26/step-26.cc b/examples/step-26/step-26.cc
index fc07cec0de..df150e3d40 100644
--- a/examples/step-26/step-26.cc
+++ b/examples/step-26/step-26.cc
@@ -434,11 +434,11 @@ namespace Step26
   // <code>goto</code> is hard to understand. In fact, deal.II contains
   // virtually no occurrences: excluding code that was essentially
   // transcribed from books and not counting duplicated code pieces,
-  // there are 3 locations in about 600,000 lines of code; we also
-  // use it in 4 tutorial programs, in exactly the same context
-  // as here. Instead of trying to justify the occurrence here,
-  // let's first look at the code and we'll come back to the issue
-  // at the end of function.
+  // there are 3 locations in about 600,000 lines of code at the time
+  // this note is written; we also use it in 4 tutorial programs, in
+  // exactly the same context as here. Instead of trying to justify
+  // the occurrence here, let's first look at the code and we'll come
+  // back to the issue at the end of function.
   template <int dim>
   void HeatEquation<dim>::run()
   {
@@ -644,10 +644,14 @@ namespace Step26
 // to read or understand than a <code>goto</code>.
 //
 // In the end, one might simply agree that <i>in general</i>
-// <code>goto</code> statements are a bad idea but be pragmatic
-// and state that there may be occasions where they can help avoid
-// code duplication and awkward control flow. This may be one of these
-// places.
+// <code>goto</code> statements are a bad idea but be pragmatic and
+// state that there may be occasions where they can help avoid code
+// duplication and awkward control flow. This may be one of these
+// places, and it matches the position Steve McConnell takes in his
+// excellent book "Code Complete" about good programming practices
+// (see the mention of this book in the introduction of step-1) that
+// spends a surprising ten pages on the question of <code>goto</code>
+// in general.
 
 
 // @sect3{The <code>main</code> function}