Building Maintainable Software – Free O’Reilly Ebook
I’m all for promoting maintainable code, but unfortunately I’d hesitate to recommend this book after looking through some of the early material.<p>For example, the first main chapter is “Write Short Units of Code”, in which the authors advocate a strict 15 lines per method limit. This sort of argument is common, but not one that seems to be supported by evidence.<p>For one thing, arbitrary limits are rarely a good idea in programming. If I take an 18 line Java function and translate it almost directly into Python, where it’s only 14 lines because I don’t need a few closing braces, is it suddenly now more maintainable? That seems unlikely.<p>More significantly in this particular case, various studies over the years have <i>not</i> supported the claim that short functions have better error rates, nor that longer but otherwise reasonable functions have higher error rates; if anything, the overall body of evidence seems to suggest the opposite conclusion.[1]<p>As the book does note itself, the problem with longer functions often isn’t their length, it’s that they are mixing up multiple responsibilities, which can’t then be read, tested, or reused separately. A better guideline here might have been to separate different responsibilities into different functions, rather than focus on the amount of code required to implement a specific responsibility cleanly. Of course, this will naturally lead to shorter functions in a lot of cases, but without the correlation&#x2F;causation fallacy.<p>For similar reasons, I wish they had treated their second substantial example (the one about the Pacman-style game board) differently. There are a few maintenance hazards with the original code that perhaps could be improved, and depending on the rest of the code there might be some useful ways to refactor that function for ease of reuse. However, the original function wasn’t awful, and it was reasonably clear what it did and how it worked. I don’t think it is an improvement to replace that with three functions and a substantial amount of shared state wrapped in a class. The code is still tightly coupled, so this offers limited benefits in terms of testing or reuse, and now the reader has to jump around different parts of almost twice as much code to figure out what is going on.<p>To add insult to injury, there is then a horrible section on common objections that tries to address the criticism that more spread out code may be harder to read. I imagine my psychologist friends would cringe at the way it appeals without evidence to probably one of the most misunderstood results in all of psychology.<p>I haven’t read the whole book, but the subsequent chapters that I have read do follow a similar pattern, in particular dismissing potential objections to the authors’ preferred style with vague arguments that lack either logical reasoning or citations of hard data. From authors who apparently have CS PhDs and talk a lot about science and software quality in their biographies, this lack of rigour is disappointing.<p>I applaud the authors for trying to raise awareness of an important and often neglected aspect of programming, but unfortunately this book looks like a missed opportunity: it’s more <i>Clean Code</i> than <i>Code Complete</i>, strong on advocacy but light on evidence and with some questionable advice.<p>[1] For anyone who wants to explore real data in this area, I suggest starting with the discussion in <i>Code Complete</i>, which helpfully cites several relevant papers from the relatively early research, and then using Google Scholar to find more recent material based on what else cites those papers.