
Reading Code: In praise of superficial beauty - llambda
http://corte.si/posts/code/reading-code.html
======
raganwald
No doubt a lot of people agree with this post, but I feel compelled to point
out that he doesn't actually present an argument, just a claim. He simply
states that a lack of superficial beauty is the best indicator of a lack of
code quality and then says it is such basic advice that it needn't be given.

It may be true, but aside from preaching to people who already believe this to
be true, what does this post give us? No statistics examining Github projcts
and correlating inconsistent indentation with defects measured.

So while the claim may be correct, I can't support this post. An interesting
post would present evidence or at least hypothesize a mechanism for the
relationship. For example:

Does inconsistent code correlate with multiple programmers working over a long
period of time, adding kludges and hacks tht dilute a design?

Are sloppy indentors sloppy thinkers on everything?

Does poor architecture have a social effect that repells good coders, until
sloppy coders are the only people that will work on it?

Personally, I suggest that one (not necessarily the only) mechanism in play on
some cases is that good programmers are interested in a wide spectrum of good
practices, and there is a correlation between any two random good practices on
this basis alone. I wager a dozen bottles of craft brewed beer there's a
statistcal correlation between consistent code style and test coverage but
absolutely zero causal relationship between the two.

A good case for one of these or any mechanism would find me far more
interested. Until then, it's folklore. It might be true, but it isn't going to
persude people as much as confirm what people think they already know.

Also, it's crucial to establish whether there's a causal relationship. Because
if not, there's a danger that everyone will rush out and go cargo cult,
formatting their code and writing style guides, with the result being highly
readable dreck. If you want to write quality code, we can't settle for an
ndicator, we need to know which practices create quality.

~~~
Derbasti
It's funny how your argument can be applied just as meaningfully to most of
the comments here. We all agree, but no-one can prove it.

~~~
raganwald
Proving it is hard, I would hate to apply that standard to my own posts! I was
trying to call for some hypotheses. Even if unproven, a hypothesis for the
mechanism is useful, becuase it spurs more focused debate, and maybe someone
else will prove or disprove it.

------
alexeiz
The code from OpenSSL in question is not bad, actually. Apart of purely
stylistic issues, this code is:

* robust, handles all error conditions,

* more or less well structured, I had no problems reading it, although I strongly prefer different coding style,

* is on par with the best examples of C code I have encountered,

* tricks like jumping into if(0) block are common for error handling in C. Once you get used to it, it reads naturally.

So get over it, people. Just because some code doesn't look like what you'd
write doesn't mean it's bad. Try to look beyond stylistic issues.

~~~
VMG
Misleading identifiers aren't stylistic issues.

~~~
eLobato
What are they then? Actually it's certainly the thing that bugs me most about
that code.

~~~
VMG
semantic errors?

------
wybo
I fully agree with this post. And it would not surprise me if parallels could
be found with the so called 'Broken Windows' (no pun intended ;) theory from
criminology.

<http://en.wikipedia.org/wiki/Broken_windows_theory>

That is, similarly to how a messy, run down environment invites anti-social
behaviour and crime, the less tidy a code-base is the more corner-cutting will
be invited on more structural levels as well...

~~~
davidcuddeback
My software engineering professor in college uses the "broken windows" theory
to teach students about technical debt.

------
hackinthebochs
I completely agree with this post. Beauty of code is directly indicative of
more meaningful quality metrics. I don't think this is merely a chance
correlation either. I think beauty itself is our minds way of noticing certain
qualities that have proven to indicate quality.

------
Ramone
I think calling it "superficial beauty" undermines the quality he's looking
for, which in my opinion is "human readability". A human has to make multiple
passes to parse something like this, and that's entirely unnecessary.

~~~
southern
Exactly. And an important factor in readable code is whether flow control
constructs can be easily followed.

------
pjscott
For an instructive example of really _good_ code, I'm a fan of the Go standard
library:

<http://golang.org/pkg/>

It's remarkably clean and well-written.

~~~
anon_d
And plan9. Written by by non-disjoint sets of people.

<http://plan9.bell-labs.com/sources/plan9/sys/src/>

------
dhx
OpenSSL isn't the best example to use. Cryptographic code is quite challenging
to write because it needs to factor in timing analysis attacks (via cache
misses, branching with different execution times, etc). For this reason, use
of normal programming approaches may be incorrect from a security standpoint.

------
HalibetLector
How do IDEs factor into this theory? It's easy to make pretty code these days
in a variety of languages without actually writing it yourself.

The other factor that comes into play is time to implement. Most startups are
always in crunch mode of one type or another. Everything needs to be done last
week, so getting it done quick is more important than getting it done right
(this is the manager's viewpoint, not mine, but it is a popular one). So you
do it and you tell yourself you'll fix it later, but later comes and you're on
to the next deadline, so it never gets re-written. Are you a bad programmer?

I appreciate the idea of beautiful code, but it doesn't survive contact with
the real world, especially if the real world is running scrum.

------
haberman
Other examples of beautiful code: Lua, LuaJIT, SQLite, tmux (I've heard)

Other examples of ugly code: screen, Perl (5.x)

------
moocow01
I get the gist, yes there is some code that is really really ugly and almost
incomprehensible at times (I'm looking at you Perl jk) but on the more
granular level of "not ugly" code I feel like beauty is somewhat in the eye of
the beholder.

One thing I get very tired of is people pushing their stylistic choices as the
beacon of good code. I think its hard for us to at times be accepting of code
that is not in our style because it can require a bit of an adjustment to
comprehend it. I've seen so many tiffs over seemingly meaningless things like
placement of curly brackets its absurd.

The example code in the article does have some stylistic things you could
nitpick on and could be pointed out in a code review but if that sets off your
alarm bells I would highly advise that you don't work at a place that does
heavy outsourcing if you want to maintain your sanity.

------
petercooper
Totally. A programmer who doesn't care about code style is like a writer who's
fine with misspellings and sloppy punctuation. The story (or algorithm) can
still be awesome but the way it's expressed matters a lot when other people
will be forming opinions from it.

~~~
dextorious
Say that to e.e. cummings' face!

~~~
LeafStorm
While the style of e.e. cummings is definitely heterodox, it isn't a perfect
analogy in this case because:

(a) his style is internally consistent with itself, instead of being a
scattering of random mistakes,

(b) while his style is different, he doesn't do anything that majorly impedes
readability, and

(c) he uses the style for a particular artistic effect, instead of just using
it because he is too lazy to press SHIFT.

------
djtriptych
I agree with the major points in the post, and even think that code format
guidelines like K&R for C, PEP8 for Python, and jslint for Javascript should
be freely broken by experienced programmers whenever the beauty of the code is
unambiguously improved.

Incidentally I just checked out the redis code base. Gorgeous:

<https://github.com/antirez/redis/tree/unstable/src>

------
mmahemoff
A counterpoint might be that Vim, Mutt, and Procmail are all highly popular,
long-lived projects. Making the case that code quality isn't the be-all and
all-all.

~~~
erikpukinskis
Of course not. It's probably not even the #1 priority for more than a handful
of projects. But I think the relevant question to pretty much everyone is: "do
investments in code quality pay off?"

Just because Vim, Mutt, and Procmail are successful doesn't mean their lack of
investment in CQ hasn't hurt them.

------
bilalhusain
the link to Marco's article is broken in the article, the correct one is
<http://www.peereboom.us/assl/assl/html/openssl.html>

------
TwoBit
Hacker News discussed this over a year ago:
<http://news.ycombinator.com/item?id=1679926>

------
mikerg87
Rather than bitch about the work that someone generously donated for your
benefit, why not roll up your sleeves and contribute a patch that makes things
"better". With FOSS you get what you pay for.

~~~
raganwald
Interesting comment, thanks!

Think about submitting a pull request to a major project reformatting the code
and renaming a lot of variables.

This will touch so much code that reviewers will consider it high risk. But it
doesn't fix any bugs, add new functionality, or refactor the code to make
something else easy. It's risky now with a hard-to-quantify payoff later. On
top of that, our current tools make this painful, a pervasive patch like this
will produce a lot of merge conflicts unless handled carefully.

I see a lot of forces acting against rolling up our sleeves and fixing code
beauty on a non-trivial project with a lot of users and committers.

~~~
astrodust
You may as well repeatedly shoot yourself in the face for all the good
cleaning up code will do. It's indented like a train-wreck because someone
wanted it that way and they will likely fight you tooth and nail to keep it as
it is.

