From: Wolfgang Bangerth 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 "Code + Complete" 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 Software Carpentry project 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 // goto 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 void HeatEquation::run() { @@ -644,10 +644,14 @@ namespace Step26 // to read or understand than a goto. // // In the end, one might simply agree that in general -// goto 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. +// goto 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 goto +// in general. // @sect3{The main function}