<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Apr 21, 2014 at 10:49 PM, Tom Mitchell <span dir="ltr"><<a href="mailto:mitch@niftyegg.com" target="_blank">mitch@niftyegg.com</a>></span> wrote:</div>
<div class="gmail_quote"> </div><div class="gmail_quote">> Teach literate programming.</div><div class="gmail_quote"> </div><div class="gmail_quote">Yes, teach the concept and the intent.</div><div class="gmail_quote">
 </div><div class="gmail_quote">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.</div>
<div class="gmail_quote"> </div><div class="gmail_quote">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.</div>
<div class="gmail_quote"> </div><div class="gmail_quote">(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.)</div>
<div class="gmail_quote"> </div><div class="gmail_quote">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.</div>
<div class="gmail_quote"><br>
-- <br>Neca eos omnes. Deus suos agnoscet. -- Arnaud-Amaury, 1209<br>
</div></div></div>