>> Method #2 suffers from the problem that there's so much chatter in the 
>> source file that you can't actually find the executable code any more. 
>> It makes small, simple modules look huge and complex.
>>
> My experience is that that's not the case.
> 
> To the contrary: Breaking up the source code with commenting blocks 
> helps give the code more structure, even if you don't change a single 
> statement.

You'd *think* it would help, but in general it just gets in the way. 
When you're trying to edit the documentation, there's all these lumps of 
code in the way, and when you're trying to edit the code, there's chunks 
of documentation in the way. (Plus, in Haskell in particular, the 
documentation tends to be vastly longer than the code.)

> In any case I guess we agree that the problem of documentation needs to 
> be addressed not by programming /languages/, but by programming 
> /environments/.

Yeah, pretty much. (The documentation is usually comments, after all. 
All languages support this.)

> I guess the ideal solution would be an IDE that is capable of managing 
> hypertextual RTF documents alongside with code, highly integrated with 
> the version management software, and for each change would ask: "What 
> was the nature of your code change, Dave?" - being smart enough to 
> identify which functions were actually changed, and also which ones 
> might be affected indirectly.

Yeah, that sounds about right. Something like Google's SideWiki.

-- 
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*

Post a reply to this message