[Cryptography] Open Source developer employment agreements, was: Cue the blamestorming

Steve Furlong demonfighter at gmail.com
Tue Apr 22 09:21:50 EDT 2014


On Mon, Apr 21, 2014 at 10:49 PM, Tom Mitchell <mitch at niftyegg.com> wrote:

> Teach literate programming.

Yes, teach the concept and the intent.

As for using it in practice, I'm not so sure. Knuth created literate
programming to address some of Pascal's problems, in particular the
requirement that program elements be presented in a rigid order and in a
single source file. The solution is not always appropriate if your
programming language of choice does not have this limitation.

Forcing or even encouraging developers to write a program in literate style
actually results in a worse product than letting them write in whatever
unstructured way and document in whatever haphazard way they normally do.
An awful lot of programmers can't or won't organize their thoughts on a
program or module in a logical, ordered fashion which lends itself to
comprehension by others. An awful lot of programmers can't or won't write
natural-language text that makes sense, let alone that anyone would want to
read. An awful lot of programmers aren't conscientious enough to update
text when they update code. If you think that outdated and inaccurate
inline comments are bad, you've seen nothing until you've seen a literate
program which has been "maintained" for a few months by three developers,
two of whom won't work on the text unless forced.

(Now, you could make the argument that programmers who can't or won't
organize their thoughts logically should be fired, and I do make that
argument, but that's a separate topic. And the same for those who don't
keep code comments up to date.)

JavaDoc and its brethren take much inspiration from literate programming.
If written properly, the generated documentation can come close to a
book-style literate program. On most coding teams, I figure this is as good
as we're likely to get.

-- 
Neca eos omnes. Deus suos agnoscet. -- Arnaud-Amaury, 1209
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.metzdowd.com/pipermail/cryptography/attachments/20140422/45395a6c/attachment.html>


More information about the cryptography mailing list