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

[Jerry Leichter]

On Apr 22, 2014, at 9:21 AM, Steve Furlong <demonfighter at gmail.com> wrote:
> 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.
And how much success do you have getting programmers to produce decent Javadoc documentation?

I've been pushing hard to get people on my current project to produce decent Javadoc (and comments in general), but it's an uphill battle.  In a previous job, we used a Javadoc-like tool for C++ whose name escapes me.  A small team of hand-picked people who worked directly for me were pretty vigilant about writing appropriate comments - though some weren't very good at it, and I ended up re-writing most of their documentation-level comments.  But beyond that, in the rest of the organization ... nada.

Unfortunately, once you've filtered out those who will do anything to avoid writing documentation/comments; and those who are willing but do such a mediocre job that it's barely worth the trouble; you don't have many people left.  It's a real challenge.
                                                        -- Jerry