January/February 2018 issue of acmqueue

The January/February issue of acmqueue is out now




ITEM not available


Originally published in Queue vol. 5, no. 6
see this item in the ACM Digital Library



Jez Humble - Continuous Delivery Sounds Great, but Will It Work Here?
It's not magic, it just requires continuous, daily improvement at all levels.

Nicole Forsgren, Mik Kersten - DevOps Metrics
Your biggest mistake might be collecting the wrong data.

Alvaro Videla - Metaphors We Compute By
Code is a story that explains how to solve a particular problem.

Ivar Jacobson, Ian Spence, Pan-Wei Ng - Is There a Single Method for the Internet of Things?
Essence can keep software development for the IoT from becoming unwieldy.


(newest first)

Andrew Raybould | Tue, 23 Aug 2011 02:41:26 UTC

The unreasonable persistence of the self-documenting code fallacy has long puzzled me too, because it is so clearly and simply refuted. Undergraduate beliefs and pretensions should not be taken seriously, but when experienced professional developers express a belief in the fallacy, the foremost question in my mind is 'what are they thinking?'

For example, when needing to use a library function or system call they are unfamiliar with, do they read its code to determine its arguments, return values, exceptions thrown, thread-safety and semantics? Of course not! If they are poor programmers, they will try to get by using examples and trial-and-error, while better programmers will read the documentation (for that matter, how did they decide that the function in question was the one they need?) Perhaps SDC believers are all applications programmers who think of the operating system and language-supplied standard libraries as some sort of deus ex machina that is not the result of programming as they understand it, and so do not recognize the contradiction between their beliefs and actions. I doubt that such a person could be much of a programmer, as libraries and other modular abstractions have an important part to play in well-designed applications as well as systems software.

In addition to wondering what are they thinking when writing code, I wonder if SDC believers ever think about the process of programming, and in particular, their own programming. Such introspection is an important part of improving one's skills, but if a programmer thinks his code is good enough that it has no need for documentation, perhaps he thinks his skills have no need of improvement. The Dunning-Kruger effect is rampant in programming; Linus Torvalds remarked that 95% of programmers think they are in the top 5%, and the rest think they are above average.

There is a school of thought, born of bitter experience, that says all comments and other documentation should be ignored, as it is rarely updated when the code is changed. Superficially, this is an argument for all code being self-documenting, but it does not follow that it can be. Furthermore, this argument fails in view of the fact that identifiers can also become misleading if there are changes in the semantics of the variables and functions they denote. For software to remain intrinsically self-documenting under maintenance, therefore, it would have to be self-documenting under arbitrary identifier renaming, which is (I hope) obviously infeasible.

I have a challenge for SDC believers: write a self-documenting implementation of the quicksort algorithm in the language of your choice, that is superior in any aspect to a combination of code and comments. The self-documented features of such an algorithm should include a proof of correctness and that it is O(n log n) on average. To anyone who says that these two issues are known properties of the algorithm, I reply: in what documentation did you read that?

Leave this field empty

Post a Comment:

© 2018 ACM, Inc. All Rights Reserved.