Git commit messages are the new Literate Programming

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:

commit d940878632e63d7f0c2af5e4ebfcf5135c48dcfb
Author: Jan Kara <jack@suse.cz>
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
    filesystem.

    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 <jbacik@fusionio.com>
    Signed-off-by: Jan Kara <jack@suse.cz>
    (cherry picked from commit 09e05d4805e6c524c1af74e524e5d0528bb3fef3)
    Signed-off-by: Willy Tarreau <w@1wt.eu>

Reminiscent of Literate Programming, no?