
Documentation Considered Harmful - thoward37
http://blog.thoward37.me/articles/documentation-considered-harmful/
======
HeWhoLurksLate
> _Insights that can only be derived through higher-order analysis are left to
> the intuition and synthesis powers of the learner_

As a robotics nerd with a _highly technical background_ and knowledge in
Visual Basic, Python, C++ and the Arduino-flavored variant of it, I _highly_
disagree. I feel that those who say "code should document itself" miss the
fact that, at least to a "novice" there's a lot of stuff that doesn't self-
reveal its purpose. For instance, the Arduino extensions to C++ are very
confusing at times, and the editor doesn't even have tooltips or the like.
Even after switching to Visual Studio Code and its Arduino extension (which is
great, BTW- thanks to anyone that's reading this who helped out on either
project) there's _still_ a lot I don't natively understand.

I personally don't document all my code, but like how third-graders don't
natively understand the Pythagorean Theorem, but can be taught it, I put
everything that I didn't understand right off the bat in my notes or my
engineering notebook, and / or in my code, often with a StackExchange link
that has a more complete explanation.

I find it somewhat offensive that _even in products targeted towards "Makers"_
where this might be their first programming project, the documentation is sub-
par and StackExchange is better, even in just pulling out some code that's
already there somewhere else. [0]

Physics doesn't speak English, you translate it in your head. Eventually. Code
is a _different language_ , that like English with its weird (I before E,
except after C, most of the time) rules, needs explanation from time to time.
We're not all college graduates with a BS in Comp Sci, and I feel like
movements like these make programming more elite and off-putting to beginners.

[0]
[https://electronics.stackexchange.com/questions/67087/analog...](https://electronics.stackexchange.com/questions/67087/analogread0oranalogreada0)

------
daly
COBOL RIDES AGAIN:

"Since programming languages are designed for humans, there is no reason they
should not be easily readable, easily comprehended, and should be sufficient
information for anyone who would like to know how a system works."

The whole idea behind COBOL was exactly that: anyone should know how a system
works by reading code.

This is obvious nonsense. It works "in the small" where the program you are
trying to understand is small. But large, complex, interacting systems would
require a person to "integrate" (as in numeric integration) from small pieces
of code to understanding the interactions (of which there are exponentially
many, too many to test) and then to infer from those interactions the
intentions of the designer, as well as the background knowledge the designer
brought to the problem.

So if a system is too complex to test under all possible inputs (which
includes rather small systems due to the exponential nature) then it is
unlikely that a human can "sit and read the code" and then understand all of
the implications.

If I'm writing code to do a complex task (e.g. handle Lidar input to
understand obstacles), I need to understand the input data stream, the "magic
numbers" that have been chosen by the sensor (likely hand-tuned with no
science behind it), the limits of the sensor (which force me to handle edge
cases in the code, also "magic"), then I need to have an idea of pixel-level
distance to the object, a model of the sensor response due to reflectivity, an
idea of "noise" (e.g. reflections off raindrops). Next I have to understand
how reflections occur off real-world objects (e.g. a truck), whether the
reflections involve one (a turning truck where I can see the back and the
side) or many (a truck next to a building). Then I have to correlate the
current input with the previous input, filtering and coordinating the "new"
solutions with the prior solutions. Finally I have to package this output in
various streams so other ROS enabled devices can subscribe and see what they
need to know in a format that is shared. Oh, and there are real-time
constraints. And we haven't even begun to talk about the SLAM algorithms
(Simultaneous Location and Mapping).

If you can get all of that from reading the code I would be amazed.

I have the source code for a computer algebra system (1.2 megabytes) that runs
under DOS on an 8086. That code varies from machine instructions to operating
system instructions to PhD level mathematics, the result of a thesis. If you
can infer the integration algorithm from the code, call me.

USE LITERATE PROGRAMMING

"Excessive documentation is a side effect of poorly written code. Modern
programming languages are just that: languages. They are a form of
communication, and when done properly, code represents a form of communication
not between a human and a machine, but between two humans, who are working
together with a machine to accomplish a task."

This was solved by Donald Knuth using Literate Programming. A literate program
compiles code that is directly embedded in the Docs. The code you see in the
Doc is the code that gets compiled. The historical flaw of software is the POS
(piles of sand) model where source code is broken up into little files and
gathered into directories. Learn literate programming.

COMMUNICATING WITH THE DEAD.

"Direct Communication (DC) involves the transference of knowledge from one
human to another without intermediaries, using natural language." Several of
the authors of the computer algebra system are dead. My local medium at the
seance sessions has trouble understanding what the dead are trying to
communicate.

To quote Monty Python: "'E's not pinin'! 'E's passed on! This parrot is no
more! He has ceased to be! 'E's expired and gone to meet 'is maker! 'E's a
stiff! Bereft of life, 'e rests in peace! If you hadn't nailed 'im to the
perch 'e'd be pushing up the daisies! 'Is metabolic processes are now 'istory!
'E's off the twig! 'E's kicked the bucket, 'e's shuffled off 'is mortal coil,
run down the curtain and joined the bleedin' choir invisible!! THIS IS AN EX-
PARROT!!"

WHO ANSWERS THEIR PHONE?

Plus there is the "fan-out" problem. As an open source maintainer I can barely
keep up with the change requests. I can't spend time explaining why the
integration algorithm we implement won't integrate your special case code. In
fact, to find that answer I'd probably have to research and write a PhD
thesis.

All I can recommend is that you download a copy of Axiom (axiom-
developer.org), read the source code, and send me your phone number. I have
questions I can't answer. I wrote some of the code in the 1980s that I no
longer understand.

Note that I gave a talk at the "Write the Docs" conference:
[http://daly.axiom-
developer.org/TimothyDaly_files/publicatio...](http://daly.axiom-
developer.org/TimothyDaly_files/publications/DocConf/LiterateSoftwareTalk.html)

