Documentation Considered Harmful

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

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