<nettime> literate programming

[Jaromil <jaromil@dyne.org>]

dear nettimers,

on 29 Dec 2014 through the public contact webform of dyne.org someone sent this
message to the hackers listening, signed as an anonymous "literate guy". I very
much feel like it deserves to be shared, as some of us here are busy with
thinking of code, power, governance, etc.

Good wisdom, follows a reply to our dear literate guy___ ""
(fixed space formatting from the original) ""
""
I like your intent to make your code as clear as possible.
In fact I was interested in your page because you claim to write
literate code, but it is not yet a literate code.

Although your code is nicely typeset, that is not the key idea behind a
literate program.

The key idea of literate programming is to make a detailed explanation
of what the program does including a description of the problem, how it
is structured and why that each choice was made among other options.
  
Instead to documenting the implemented method, as it is usually done
with comments beside each function / procedure  header  and each  type /
class definition,
a literate program, should first explain in detail the problem that the
program solves, defining the meaning of each element.
 
Literate programming is like writing a mathematics or physics book, you
must first define the things you are talking about.  

In a physics book, a diagram showing an inclined plane showing the
forces acting on a particle is first presented to explain that the
forces may be separated in x and y direction.  
After an explanation on how the forces act, it comes  the translation
into mathematical equations, then some algebraic transformations are
made to simplify them.
Finally the variables are substituted by the problem\'s values and the
answer is calculated.

Literate programming is analogous to such style of writing. By first
explaining the problem in natural language or even by the help of
diagrams and any other kind of examples, bibliographic cites should be
included when available. 
Usually the next is to explain how each thing is going to be formally
represented, which makes clear exactly what thing is represented by each
data type,  and what transformations can be performed on those objects,
that explains what each function / procedure does.

A volunteer new to the subject can understand what the program  does.

Like those equations in the physics text example, programs are also
subject to an algebraic manipulation, it is not often done rigorously,
but decisions are taken to prevent memory leaks, improve performance,
avoid concurrency problems like deadlocks, etc.

Being more ambitious the piece of code being written may include a
formal proof that it solves what the problem states.

In few words you explain your decisions until you can display a great
piece of code. That piece of code which is displayed like the equations
in the physics text, is what is processed by the compiler / interpreter.
Everything else is a huge comment.

The full documentation of the program and the source are in the same
document.

There are several ways to do a nice typesetting, depending on the chosen
programming language. 
A program is needed to separate and sort the program text and the
typesetting code.

Literate programming was first proposed and used by Donald E. Knuth, 
when writing the typesetting system TeX.  He used Pascal to write it,
and used a program called Web for preprocessing the literate source to
generate the TeX and Pascal sources.

New programs some derived from Web, exist in order to do the
preprocessing job, but TeX/LaTeX is still the best option to write all
the literate explanation.

I hope that you find this message useful and your gradual adoption of
this programming style in full to become pioneers in Hyper Free
Software, a step beyond Free Software which easies the collaboration of
non dedicated volunteers adding new features to programs. No need to say
that this style improves the software quality and life.
""
dear literate guy___"


Many thanks for your remarks. I removed the "literate programming" label from
the Tomb webpage after reading you, feeling a bit ashamed. But then it wasn't
there when we last hit Slashdot and many coder teens could have scratched their
head on the term.

However not perfect, we all grow in the same spirit, deep comprehension of what
code means to people and the importance of what you teach us to be literate
programming.

The Freaknet sisterhood and brotherhood listens to your good words. Some
of us are engaging Clojure programming, many learning the way of
minimalism and readability, all using clean terminals. I'm happy to see
that the world is moving towards functional languages, stateless and non
imperative. A good example is the new packaging system Guix.

We hope the world at large understands the importance of minimalism.
It does not only concerns technology but the societies at large.
and yes, it is beyond Free Software, but still pretty much GNU :^)

Current software projects we develop at Dyne.org inspired by minimalism

http://Dev-1.org

http://dowse.equipment

http://dyne.org/software/tomb

ciao


-- 
Denis Roio aka Jaromil   http://Dyne.org think &do tank
  CTO and co-founder      free/open source developer
GNUPG 6113 D89C A825 C5CE DD02 C872 73B3 5DA5 4ACB 7D10


#  distributed via <nettime>: no commercial use without permission
#  <nettime>  is a moderated mailing list for net criticism,
#  collaborative text filtering and cultural politics of the nets
#  more info: http://mx.kein.org/mailman/listinfo/nettime-l
#  archive: http://www.nettime.org contact: nettime@kein.org