
Building Maintainable Software – Free O’Reilly Ebook - ingve
https://www.sig.eu/en/building-maintainable-software/
======
antouank
This is also a great book, from the creator of ESLint, with similar topic
[http://shop.oreilly.com/product/0636920025245.do](http://shop.oreilly.com/product/0636920025245.do)
.

------
Chris_Newton
I’m all for promoting maintainable code, but unfortunately I’d hesitate to
recommend this book after looking through some of the early material.

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.

~~~
nimnio
"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."

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.

~~~
Chris_Newton
_That 's an oversimplification of the research, and misleading._

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.

------
kluck
Great topic and from scanning the table of contents the guidelines are well
chosen. The matter maintainability is discussed far too seldom!

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".

~~~
crististm
Maintainability is not the first topic of discussion when mantra is "build
software to throw away".

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.

~~~
adrianN
I guess it depends on your perspective. I'd argue the exact opposite; we're
entering the age of huge, ancient, yet mission critical codebases that nobody
really understands. Look at any piece of popular business software, eg SAP, or
the software controlling most computer powered machinery, like factories.

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.

