Literate Programming is a style of programming invented by Donald Knuth in which, instead of the usual style of embedding comments in code, you instead embed code in comments. The result is a long narrative of prose (describing how you are writing the code) with code snippets interspersed throughout.
This never caught on. Perhaps because programmers don't like writing documentation? However, I have noticed something interesting. Sophisticated programmers today write lengthy commit messages. It is an example set by the Linux kernel committers - check out their wonderfully descriptive commit messages. (I first learned about the high quality of Linux kernel commit messages from 5 Useful Tips For A Better Commit Message.)
It strikes me now - I wonder if commit messages are the new Literate Programming. It is said that programmers don't like writing documentation, but they seem to willingly put a lot of effort into writing long, descriptive commit messages. Here's an example of a meaty commit message from the Linux kernel:
Author: Jan Kara <firstname.lastname@example.org>
Date: Wed Jul 11 23:16:25 2012 +0200
jbd: Fix assertion failure in commit code due to lacking transaction credits
ext3 users of data=journal mode with blocksize < pagesize were occasionally
hitting assertion failure in journal_commit_transaction() checking whether the
transaction has at least as many credits reserved as buffers attached. The
core of the problem is that when a file gets truncated, buffers that still need
checkpointing or that are attached to the committing transaction are left with
buffer_mapped set. When this happens to buffers beyond i_size attached to a
page stradding i_size, subsequent write extending the file will see these
buffers and as they are mapped (but underlying blocks were freed) things go
awry from here.
The assertion failure just coincidentally (and in this case luckily as we would
start corrupting filesystem) triggers due to journal_head not being properly
cleaned up as well.
Under some rare circumstances this bug could even hit data=ordered mode users.
There the assertion won't trigger and we would end up corrupting the
We fix the problem by unmapping buffers if possible (in lots of cases we just
need a buffer attached to a transaction as a place holder but it must not be
written out anyway). And in one case, we just have to bite the bullet and wait
for transaction commit to finish.
Reviewed-by: Josef Bacik <email@example.com>
Signed-off-by: Jan Kara <firstname.lastname@example.org>
(cherry picked from commit 09e05d4805e6c524c1af74e524e5d0528bb3fef3)
Signed-off-by: Willy Tarreau <email@example.com>
Reminiscent of Literate Programming, no?