Building Maintainable Software – Free O’Reilly Ebook
sig.eu
sig.eu
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.
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.
More significantly in this particular case, various studies over the years have not 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]
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/causation fallacy.
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.
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.
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.
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 Clean Code than Code Complete, strong on advocacy but light on evidence and with some questionable advice.
[1] For anyone who wants to explore real data in this area, I suggest starting with the discussion in Code Complete, 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.
That's an oversimplification of the research, and misleading. After citing five studies in Code Complete (including the one that shows an inverse correlation between errors and function size), McConnell summarizes as follows:
"That said, if you want to write routines longer than about 200 lines, be careful. None of the studies that reported decreased cost, decreased error rates, or both with larger routines distinguished among sizes larger than 200 lines, and you’re bound to run into an upper limit of understandability as you pass 200 lines of code."
I wouldn't advocate for a strictly short functions either, but the overall body of evidence definitely does _not_ suggest the opposite conclusion: the opposite conclusion would be that we should endeavour to write long functions!
Anyhow, nitpicking aside, thanks for providing a quick review of this book. I'm going to skip it based on your comments.
OK, I concede that I simplified there, though I think you’re being a little harsh. When we’re discussing shorter vs. longer functions today, it seems fair to say we’re usually considering scales of perhaps 5 lines vs. 25 lines vs. 100 lines. I did write “longer but otherwise reasonable”, and by the time we’re talking about 200+ lines in a single function, I expect most of us would consider most such functions undesirable for reasons other than their length.
I wouldn't advocate for a strictly short functions either, but the overall body of evidence definitely does _not_ suggest the opposite conclusion: the opposite conclusion would be that we should endeavour to write long functions!
Well, some of the evidence does seem to suggest that that might be a better strategy, within the bounds of common sense and other things being equal.
However, in reality, I don’t think other things are equal most of the time in programming. Personally, I find criteria like having one responsibility and clearly describing how it is met more useful for writing good functions than crude metrics like the number of lines.
Given that there are a lot of correlations between otherwise undesirable features and function length, we should be wary of assuming causal relationships in any case. But we surely shouldn’t be advocating the trendy very-short-functions approach as some obviously superior style when if anything the balance of evidence is against it.
Comments are valuable in only a small number of cases. Helpful API documentation
can be such a case, but always be cautious to avoid dogmatic boilerplate commentary.
In general, the best advice we can give is to keep your code free of comments.
They seemed to work (i.e. had no obvious deficiencies), but there's more to code quality than error rates. Functions should be readable, easily modifiable, testable, and in many cases reusable.
Apart from possibly initialization code and functions containing large switch statements, I limit function length in my own code to a screenful: more precisely, one sheet of A4 paper if printed. (60 lines, 80 columns.)
See also 10 Rules for Writing Safety Critical Code (http://spinroot.com/p10/) Rule 4.
I think of Twitter as an example of the brevity problem. On the one hand, the size limit has resulted in some very neat tweets that manage to say a lot in a little space. On the other hand, we ended up with things like super-short URLs that completely remove any hint about their meaning in the name of brevity. One limitation managed to both improve and damage at the same time.
In principle, shorter is better. But if something needs to be 20 vs 15, nobody is going to panic.
What properties of 100-250-line methods make them optimal?
I would like to add that "maintainability" more often than not refers to maintenance "by someone else other than who wrote the first revision of some code".
We're in an age of consumerism in software. We reinvent large pieces of software because we don't have a grip on existing ones to be able to repair or extend them. All the known acronyms including NIH are at work.
It's layers upon layers dating back to the 80s. The systems perform poorly even on modern machines, and have terrible usability because changing them is too hard.