On Tue, 19 Apr 2011 20:45:29 -0700, Darren New wrote:

> On 4/19/2011 19:01, Jim Henderson wrote:
>> that that's what comments are for. ;)
> 
> Comments help with localized pieces of code. If I hand you something
> like Apache or Outlook or the Linux kernel, in-line comments are not
> going to tell you what order to read code in to learn how it works. 
> Especially if fixing some specific bug is your first task. Sure, someone
> can show you *this* piece of code parses configuration files and *that*
> piece of code handles authentication, but that's a person showing you
> that, or hours wandering around looking for an anchor. And that's even
> assuming the code is well structured to start with.

Well, yes, I do know what you mean.  Even with proper code analysis 
tools, it can be difficult to read code.

It's far easier if, for instance, you're using a tool like Source 
Navigator (which I really like for this type of thing) you are looking to 
analyze a bug.  Having an error code and a call stack makes it far easier 
to use a tool like that than to say "I wonder how it does 'x'" and then 
work through the logic.  It's possible, but it can take quite a while.

Proper documentation includes design documents and the like - and that 
certainly goes a lot further than code alone.

Jim

Post a reply to this message