![](/i/fill.gif) |
![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 4/19/2011 23:02, Jim Henderson wrote:
> 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.
Here's the thing about that...
There are three steps to debugging a piece of code:
1) Find the symptoms of an error and confirm it's erroneous.
2) Find the program state (i.e., variable values) that isn't as expected at
that point.
3) Trace back the infected state to the defect in the code that caused the
original infected state.
4) Determine how to modify the code to no longer have that defect, hopefully
without introducing infected state that triggers an error from a defect
existent elsewhere.
An error code and a call stack gives you #1. But if you don't know what the
program state is supposed to look like, all you have to go on is the actual
variables that show the error message. I.e., if you don't know even the
slightest amount of what the data in a structure is supposed to be, then
having an error message tell you that a particular pointer is null when it
shouldn't be doesn't help nearly as much as looking at the values and
determining every value in the entire structure is zero when it should all
be filled out with good data.
What's the good data? *That* is what needs to be documented. Otherwise,
you're reading the code, trying to figure out what the code *does*, and once
you do, you *still* haven't even *started* to find the bug. Then you have to
guess what the author *intended* to have happening there, and then guess
from that what the state should have been. *Now* you've finished step #1.
With documentation, all that is tremendously simplified or eliminated,
depending on how detailed the documentation is.
Saying "the code is the documentation" is like saying "the commercial
airliner doesn't need maintenance documentation. You can just look at it and
see what's wrong."
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
Le 2011/04/20 10:52, Darren New a écrit :
> On 4/20/2011 1:25, Invisible wrote:
>> That's not even shareware any more. You get a free 30-day trail, and
>> after
>> that you're legally required to pay for it.
>
> I think that's how it has always been.
30 days, 60 days, 5 uses, 10 uses, 30 uses, 45 uses, 60 uses and 90 uses
are at least somewhat common.
>
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
Le 2011/04/19 20:10, Darren New a écrit :
> On 4/19/2011 17:06, Jim Henderson wrote:
>> On Tue, 19 Apr 2011 16:48:35 -0700, Darren New wrote:
>>
>>>> Most OSS projects rely on code as the internal documentation.
>>>
>>> Code is not documentation. Anyone who thinks that code *is*
>>> documentation on any project you feel the need to split into multiple
>>> files is fooling themselves.
>>
>> Of course, that was pretty much what I said in the next sentence after
>> what you quoted.
>
> Even if everyone uses the same style, code isn't documentation. Even if
> only one person works on the code ever, code isn't documentation. Code
> is no more documentation than the steering wheel is your turn signals.
>
Comments, comments, comments and more comments.
That's the only way that code can be used as documentation. That's when
the documentation is actualy writen in human readable form alongside of
the code itself.
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 4/20/2011 10:37, Alain wrote:
> Comments, comments, comments and more comments.
> That's the only way that code can be used as documentation.
Yep. And that assumes you know the right place to look in the code to find
the documentation. Without an overview, you wind up guessing which source
files of which subdirectories you need to read for comments.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
Le 2011/04/20 14:23, Darren New a écrit :
> On 4/20/2011 10:37, Alain wrote:
>> Comments, comments, comments and more comments.
>> That's the only way that code can be used as documentation.
>
> Yep. And that assumes you know the right place to look in the code to
> find the documentation. Without an overview, you wind up guessing which
> source files of which subdirectories you need to read for comments.
>
You start the main with a big comment block that contains an exaustive
overview of the project. It's then followed by a table of content and an
index...
Then, each individual source files also contains a specific overview of
the function(s) of the following code, what kind of data it expect and
what kind of data it's expected to return. Don't forget the local table
of content and index.
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On Wed, 20 Apr 2011 07:58:46 -0700, Darren New wrote:
> On 4/19/2011 23:02, Jim Henderson wrote:
>> 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.
>
>
> Here's the thing about that...
>
> There are three steps to debugging a piece of code:
>
> 1) Find the symptoms of an error and confirm it's erroneous.
>
> 2) Find the program state (i.e., variable values) that isn't as expected
> at that point.
>
> 3) Trace back the infected state to the defect in the code that caused
> the original infected state.
>
> 4) Determine how to modify the code to no longer have that defect,
> hopefully without introducing infected state that triggers an error from
> a defect existent elsewhere.
My experience (recently, anyways) is somewhat limited, but I have done
diagnosis with code+change documentation+snavigator+error code+call
stack. Fairly complex software, too.
But the code in question is pretty clean and even though there's millions
of lines of code, tracing the problem back to the root cause was pretty
simple given the proper tools.
> An error code and a call stack gives you #1. But if you don't know what
> the program state is supposed to look like, all you have to go on is the
> actual variables that show the error message. I.e., if you don't know
> even the slightest amount of what the data in a structure is supposed to
> be, then having an error message tell you that a particular pointer is
> null when it shouldn't be doesn't help nearly as much as looking at the
> values and determining every value in the entire structure is zero when
> it should all be filled out with good data.
>
> What's the good data? *That* is what needs to be documented.
> Otherwise, you're reading the code, trying to figure out what the code
> *does*, and once you do, you *still* haven't even *started* to find the
> bug. Then you have to guess what the author *intended* to have happening
> there, and then guess from that what the state should have been. *Now*
> you've finished step #1. With documentation, all that is tremendously
> simplified or eliminated, depending on how detailed the documentation
> is.
>
> Saying "the code is the documentation" is like saying "the commercial
> airliner doesn't need maintenance documentation. You can just look at it
> and see what's wrong."
I have to admit I like that way of looking at it. :)
Jim
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 4/20/2011 13:01, Jim Henderson wrote:
> I have to admit I like that way of looking at it. :)
Elegantly described in detail here, along with what to do about it:
http://www.whyprogramsfail.com/
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 4/20/2011 11:33, Alain wrote:
> Le 2011/04/20 14:23, Darren New a écrit :
>> On 4/20/2011 10:37, Alain wrote:
>>> Comments, comments, comments and more comments.
>>> That's the only way that code can be used as documentation.
>>
>> Yep. And that assumes you know the right place to look in the code to
>> find the documentation. Without an overview, you wind up guessing whic
h
>> source files of which subdirectories you need to read for comments.
>>
>
> You start the main with a big comment block that contains an exaustive
> overview of the project. It's then followed by a table of content and a
n
> index...
>
> Then, each individual source files also contains a specific overview of
the
> function(s) of the following code, what kind of data it expect and what
kind
> of data it's expected to return. Don't forget the local table of conten
t and
> index.
I'm at a loss as to why such would be in comments in source code, but OK.
:-)
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 20-4-2011 23:53, Darren New wrote:
> On 4/20/2011 13:01, Jim Henderson wrote:
>> I have to admit I like that way of looking at it. :)
>
> Elegantly described in detail here, along with what to do about it:
>
> http://www.whyprogramsfail.com/
Suspiciously absent from the blurb is 'how to prevent them'.
Suspiciously present is a foreword by a MS employee.
Coincidence? you'll be the judge.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
On 4/20/2011 15:07, andrel wrote:
> Suspiciously absent from the blurb is 'how to prevent them'.
Actually, the beginning of the book basically says "there's lots of books
about preventing bugs. This is a book about fixing them once they happen."
He's very clear about that.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |