 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 21:31:20 +0100, Orchid XP v8 wrote:
> I remember reading about a memory of library stuff who saw somebody
> using Telnet. She screamed "OH MY GOD, YOU'RE HACKING OUR COMPUTERS!!!"
> and turned the computer off at the wall. The guy tried to explain what
> he was actually doing, but she wouldn't have it.
>
> Apparently there are a lot of stupid people...
There are a lot of uneducated people, certainly.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 19/04/2011 10:11 PM, Jim Henderson wrote:
> On Tue, 19 Apr 2011 21:31:20 +0100, Orchid XP v8 wrote:
>
>> I remember reading about a memory of library stuff who saw somebody
>> using Telnet. She screamed "OH MY GOD, YOU'RE HACKING OUR COMPUTERS!!!"
>> and turned the computer off at the wall. The guy tried to explain what
>> he was actually doing, but she wouldn't have it.
>>
>> Apparently there are a lot of stupid people...
>
> There are a lot of uneducated people, certainly.
Being uneducated is one thing. Assuming that you know what you're
talking about when you don't is another.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Man, I hope the ratings are *awesome*! :-D
>
> You bet, but you need to do better with the product placement. :)
OMG, you guys know where I place my products?! o_O
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 14:07:26 -0700, Darren New wrote:
> On 4/19/2011 11:40, Jim Henderson wrote:
>> Good documentation with crap software doesn't really go far either.
>
> True, but at least with half-decent documentation, people might be more
> willing to help. If you can't even tell if what you're doing was
> *supposed* to work, even those who could improve it will be at a loss.
I kinda agree with you on this point - a lot of development is done in a
very collaborative way, so those who could/want to improve tend to not
work in isolation, but as part of a team that has ongoing communication.
In that respect, OSS isn't much different from closed-source development
(at least not in my experience). Closed-source software is developed
before documentation is completed - documentation tends to start being
written when the product is installable, because the screens (for
example) tend to change before release.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>>> Plus, "redirector" and "connector" are terms that SMB uses to describe
>>> the different parts of the stack.
>>
>> Great if you already happen to know about that somehow.
>
> It's your job to learn this stuff. Now you know. Go read up how it
> works. :-)
Like, where?
>> Oh, wait. Windows costs hundreds of pounds, while Linux is given away for
>> free. Hmm, OK, maybe I should complain. :-P
>
> But it *is* documented. Indeed, I gave you the microsoft links that
> document it.
You have me a link that explains what event 3019 is. It doesn't explain
why the redirector exists or what it does or indeed anything further...
> Why do you keep complaining that Microsoft doesn't
> document this stuff, especially in response to a thread that points you
> at the microsoft documentation found with a trivial search of the obvious?
See above.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/19/2011 14:19, Jim Henderson wrote:
> I kinda agree with you on this point - a lot of development is done in a
> very collaborative way, so those who could/want to improve tend to not
> work in isolation, but as part of a team that has ongoing communication.
Bringing someone up to speed on the internals of a project that has no
internal documentation is extremely time consuming.
> In that respect, OSS isn't much different from closed-source development
> (at least not in my experience). Closed-source software is developed
> before documentation is completed - documentation tends to start being
> written when the product is installable, because the screens (for
> example) tend to change before release.
End-user documentation, yes. But most of the OSS projects are released
before there's any internal documentation either. Usually even worse.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/19/2011 14:21, Orchid XP v8 wrote:
> You have me a link that explains what event 3019 is. It doesn't explain why
> the redirector exists or what it does or indeed anything further...
On the same page, I gave you a link to an explanation of SMB caches and, if
you looked, a whole bunch of other tables of contentses.
Or type in "smb tutorial". (I've found that "tutorial" is a good keyword.)
http://oreilly.com/catalog/samba/chapter/book/ch03_03.html
"What is an smb redirector"
http://msdn.microsoft.com/en-us/library/aa939514%28v=winembedded.5%29.aspx
What do you want to learn about? People publish books and technical papers
for all this stuff. You just have to want to read it.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/19/2011 14:07, Jim Henderson wrote:
> I don't see that that matters - they document that it's informational and
> nothing to worry about.
*And* they tell you what it means, so it's trivial to confirm that it's
nothing to worry about.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2011/04/19 16:31, Orchid XP v8 a écrit :
>>> Admittedly I don't know hundreds of thousands of people. Still, the vast
>>> majority of people I know IRL don't know what Linux is, have never heard
>>> of Firefox, and think MS Office is the only "proper" office suite. You
>>> know, as if anything you can download for free off the Internet is
>>> either an illegal pirate copy or a shoddy imitation.
>>
>> Many people do feel that way. I remember reading a story in the past
>> year about a teacher who told a student to get rid of that Linux stuff
>> because they must've pirated it - nobody gives stuff away for free.
>
> I remember reading about a memory of library stuff who saw somebody
> using Telnet. She screamed "OH MY GOD, YOU'RE HACKING OUR COMPUTERS!!!"
> and turned the computer off at the wall. The guy tried to explain what
> he was actually doing, but she wouldn't have it.
>
> Apparently there are a lot of stupid people...
>
Look at
http://www.rinkworks.com/stupid/
for many samples.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 14:24:20 -0700, Darren New wrote:
> On 4/19/2011 14:19, Jim Henderson wrote:
>> I kinda agree with you on this point - a lot of development is done in
>> a very collaborative way, so those who could/want to improve tend to
>> not work in isolation, but as part of a team that has ongoing
>> communication.
>
> Bringing someone up to speed on the internals of a project that has no
> internal documentation is extremely time consuming.
Sure, but that's different than poor end-user documentation, that's what
I'm saying.
>> In that respect, OSS isn't much different from closed-source
>> development (at least not in my experience). Closed-source software is
>> developed before documentation is completed - documentation tends to
>> start being written when the product is installable, because the
>> screens (for example) tend to change before release.
>
> End-user documentation, yes. But most of the OSS projects are released
> before there's any internal documentation either. Usually even worse.
Most OSS projects rely on code as the internal documentation. Which I
don't necessarily think is a good thing since not everyone codes in the
same style (though it helps when a project has coding style guidelines, I
think).
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 22:18:49 +0100, Orchid XP v8 wrote:
> On 19/04/2011 10:11 PM, Jim Henderson wrote:
>> On Tue, 19 Apr 2011 21:31:20 +0100, Orchid XP v8 wrote:
>>
>>> I remember reading about a memory of library stuff who saw somebody
>>> using Telnet. She screamed "OH MY GOD, YOU'RE HACKING OUR
>>> COMPUTERS!!!" and turned the computer off at the wall. The guy tried
>>> to explain what he was actually doing, but she wouldn't have it.
>>>
>>> Apparently there are a lot of stupid people...
>>
>> There are a lot of uneducated people, certainly.
>
> Being uneducated is one thing. Assuming that you know what you're
> talking about when you don't is another.
That's a fair point - and something everyone should keep in mind when
making unsupportable declarations. ;)
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 22:19:16 +0100, Orchid XP v8 wrote:
>>> Man, I hope the ratings are *awesome*! :-D
>>
>> You bet, but you need to do better with the product placement. :)
>
> OMG, you guys know where I place my products?! o_O
LOL
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 14:31:42 -0700, Darren New wrote:
> On 4/19/2011 14:07, Jim Henderson wrote:
>> I don't see that that matters - they document that it's informational
>> and nothing to worry about.
>
>
> *And* they tell you what it means, so it's trivial to confirm that it's
> nothing to worry about.
Yep.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2011/04/19 11:46, Darren New a écrit :
> On 4/19/2011 2:45, Invisible wrote:
>> I don't personally know of anybody who actually sent a cheque
>
> AFAIK, I'm the only person in the entire world that ever paid for WinZip.
>
I did pay for PK Zip, then found free alternatives that both zipped
beter (faster and beter compression), and supported many formats beside ZIP.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/19/2011 15:21, Jim Henderson wrote:
> Sure, but that's different than poor end-user documentation, that's what
> I'm saying.
Sure. It's two different problems, and they're both problems.
> 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.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Tue, 19 Apr 2011 17:10:44 -0700, Darren New wrote:
> 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.
Code in and of itself doesn't include why, but one could argue (though
I'd have to admit that it would be pointless to argue it with you or any
other professional coder <g>) that that's what comments are for. ;)
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
And once it grows, you're just screwed. I mean, really, something like the
Linux kernel is really a fairly small system compared to some of the big
systems out there. (There it is. Linux is 14 million lines of code. AT&T
TURKS is 100 million lines of *SQL*, let alone all the systems that use it.)
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> I remember reading about a memory of library stuff who saw somebody
>> using Telnet. She screamed "OH MY GOD, YOU'RE HACKING OUR COMPUTERS!!!"
>> and turned the computer off at the wall. The guy tried to explain what
>> he was actually doing, but she wouldn't have it.
>>
>> Apparently there are a lot of stupid people...
>
> Look at
> http://www.rinkworks.com/stupid/
> for many samples.
http://www.rinkworks.com/stupid/cs_paranoia.shtml
My story is about half way down. ;-)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 19/04/2011 16:46, Darren New wrote:
> On 4/19/2011 2:45, Invisible wrote:
>> I don't personally know of anybody who actually sent a cheque
>
> AFAIK, I'm the only person in the entire world that ever paid for WinZip.
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. It's just that nobody
does. (I have no idea if PKZIP was shareware...)
Personally, I just use 7zip.
>> without the net it would have been infeasible.
>
> Yep. And without Windows it would have been infeasible too, because
> there wouldn't be enough people with compatible hardware to have a hope
> in hell of getting it working on enough varieties of machines to make it
> worthwhile.
How did all the other Unicies work?
>> of a lot of money for a program that doesn't even *do* very much and
>> isn't especially complicated.
>
> This coming from the guy who can't find the documentation on how to make
> it do stuff? :-) Granted, most people don't use most of its
> sophisticated features, but saying Word doesn't do much is like saying
> LaTeX just translates one text file into another format, no biggie.
LaTeX *does* just translate a text file into another format. ;-) About
the only special thing about it is that it has a Turing-complete textual
substitution engine and a sophisticated layout constraint solver. It
surprises me that nobody has yet taken the sophisticated layout engine
and put it into a modern piece of software...
>> Silly me, I'm thinking that prices have something to do with what it
>> costs
>> to produce something. This is the 21st century. Prices are driven by how
>> much you can rip people off and get away with it...
>
> They always have been.
Apparently I'm getting old. It used to be that people expected to *get*
something for their money - and if they didn't, they took it elsewhere.
Or at least, I'm now old enough to delude myself that this is how it
used to work.
> Next time you have a problem, I'll show you how to find the answer. It's
> generally not difficult, altho sometimes it can be ugly.
Any idea why printing through Terminal Services keeps breaking for no
apparent reason?
[You used to have to install an identical print driver on the TS server
or it wouldn't work. Apparently they fixed that now, so that's not it.]
I can understand it never working in the first place. What I can't
understand is why it works perfectly, and then one day one particular
user can't print anymore.
> Especially if
> they've rearranged their site and you start getting 404's. Really,
> Microsoft? You run Bing but you haven't figured out how to not have
> internal links to broken pages?
How or to clearly document when a hotfix is included in some later
hotfix or service pack. Or clearly state what product version(s) the
information in a document applies to. Or...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
> How did all the other Unicies work?
They were all processor-specific. You bought it from the hardware vendor,
just like you bought Apple DOS from Apple, TRS-DOS from Tandy, etc.
>> Next time you have a problem, I'll show you how to find the answer. It's
>> generally not difficult, altho sometimes it can be ugly.
>
> Any idea why printing through Terminal Services keeps breaking for no
> apparent reason?
Wow. OK, step one, learn to file a bug report.
When you go to the mechanic, do you say "my car's wrong, fix it"? Or do you
actually describe the symptoms, what you tried to do to fix it, what search
terms you used, etc?
> How or to clearly document when a hotfix is included in some later hotfix or
> service pack.
I've seen few rollups that didn't list the hotfixes included, or how to tell
whether you need a hotfix or how to tell whether you already have it, if you
actually read the KB article about it.
> Or clearly state what product version(s) the information in a
> document applies to. Or...
Oh come on.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 20/04/2011 22:53, Darren New wrote:
> I'm at a loss as to why such would be in comments in source code, but
> OK. :-)
Some people do advocate putting all your documentation inside your
source code.
On the one hand, the idea is that the documentation is more likely to
stay in sync with the source code. (E.g., if you swap the order of the
arguments to a function, the documentation is right next to it, so you
can update that as well.)
On the other hand, your source code is now littered with miles of text
which have nothing to do with the compiler error you're now getting...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/21/2011 1:11, Invisible wrote:
> On the one hand, the idea is that the documentation is more likely to stay
> in sync with the source code. (E.g., if you swap the order of the arguments
> to a function, the documentation is right next to it, so you can update that
> as well.)
I have no problem with that for how the source code works.
I would object to something like storing RFC822 as comments inside your SMTP
implementation.
> On the other hand, your source code is now littered with miles of text which
> have nothing to do with the compiler error you're now getting...
Which also forces a recompile every time you change it, and means anyone
writing (or reading) technical documentation has to have access to the code,
potentially breaking stuff when they accidentally modify the file.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> I have no problem with that for how the source code works.
>
> I would object to something like storing RFC822 as comments inside your
> SMTP implementation.
Yeah, that's really not very appropriate.
>> On the other hand, your source code is now littered with miles of text
>> which
>> have nothing to do with the compiler error you're now getting...
>
> Which also forces a recompile every time you change it, and means anyone
> writing (or reading) technical documentation has to have access to the
> code, potentially breaking stuff when they accidentally modify the file.
I think we can perhaps summarise this:
Embedding the API reference in the source code might be a good idea.
Embedding the end-user documentation in the source code is a terrible idea.
As an aside, everyone in the Haskell world seems to document their stuff
using a tool called Haddock. Like Java's docgen (and presumably a
bazillion similar tools), it takes source code comments and builds an
API reference from it.
What it *doesn't* really let you do in a consistent way is write "this
is WTF this project actually does and how it's structured" type
documentation, which tends to be completely absent as a direct result...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> I would object to something like storing RFC822 as comments inside your
>> SMTP implementation.
>
> Yeah, that's really not very appropriate.
I may be incorrect here, but didn't Knuth embed The TeX Book in the
source code for TeX?
(This would IMHO fall under the category of "utterly inappropriate".)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/21/2011 8:37, Invisible wrote:
> Embedding the API reference in the source code might be a good idea.
> Embedding the end-user documentation in the source code is a terrible idea.
Embedding overview-for-maintainers as comments distributed throughout the
project is a bad idea. Embedding code samples as comments in the source
code is a bad idea. Embedding design decision discussions as comments is a
bad idea.
> What it *doesn't* really let you do in a consistent way is write "this is
> WTF this project actually does and how it's structured" type documentation,
> which tends to be completely absent as a direct result...
That's precisely my point.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/21/2011 8:39, Invisible wrote:
>>> I would object to something like storing RFC822 as comments inside your
>>> SMTP implementation.
>>
>> Yeah, that's really not very appropriate.
>
> I may be incorrect here, but didn't Knuth embed The TeX Book in the source
> code for TeX?
Literate programming is something different. In that case, you simply have
one file that has both the compilable code and the documentation discussing
it, with a tool to extract the two. If you have a programming language in
which comments are *designed* to generate books with tables of contents and
all that sort of stuff, and what you're documenting is the process of
writing the code, then sure, that's not bad.
That's not what I'd consider "comments in the code", tho.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> I may be incorrect here, but didn't Knuth embed The TeX Book in the
>> source code for TeX?
>
> Literate programming is something different.
>
> That's not what I'd consider "comments in the code", tho.
I'm not sure what the difference is.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2011/04/20 17:53, Darren New a écrit :
> 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 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.
>
> I'm at a loss as to why such would be in comments in source code, but
> OK. :-)
>
It's pushing the concept of "the source code is the documentation" to
the extreme, and boldly entering the realm of absurdity ;)
To boldly code where no one have coded before :P
Alain
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 21-4-2011 4:31, Darren New wrote:
> 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.
I don't own the book. I only saw the page you linked to.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 21-4-2011 18:33, Darren New wrote:
> On 4/21/2011 8:39, Invisible wrote:
>>>> I would object to something like storing RFC822 as comments inside your
>>>> SMTP implementation.
>>>
>>> Yeah, that's really not very appropriate.
>>
>> I may be incorrect here, but didn't Knuth embed The TeX Book in the
>> source
>> code for TeX?
>
> Literate programming is something different. In that case, you simply
> have one file that has both the compilable code and the documentation
> discussing it, with a tool to extract the two. If you have a programming
> language in which comments are *designed* to generate books with tables
> of contents and all that sort of stuff, and what you're documenting is
> the process of writing the code, then sure, that's not bad.
I have used it in the past and in my experience it works extremely well.
Most importantly because both me and the colleague that were developing
a large package *enjoyed* writing nice documentation. Becasue the
documentation is generally on the level of small chunks (10-50 lines) we
tended more to document the why than the actual implementation
('increase counter by one')
I effectively stopped slowly when he left. He had it all nicely set up
on a linux box. With all sorts of interlocking make files and scripts*.
The Windows environment is more geared towards instant satisfaction.
Press a button and it will automatically build. Pity if you want
something done at some specific time during the compilation process, we
though about it and you (who we assume to be a below average user) don't
need that.
It is entirely possible that even in a Windows environment I might have
been able to get something workable in the end, but I did not have the
time and money to research it properly. Knowing that it is almost
trivial within the un*x way of thinking might have played a role.
When I switch to a linux box (that might be soon, because of ICT
department in the hospital**) I'll try to recreate such an environment.
*) Some changes might trigger a tool to create a tool to be rebuild. It
could cause a chain of extracting the C and Matlab files from a source
file. Call one of the matlabfiles to create an image for metapost, call
metapost. Include the resulting figure in the documentation. Rebuild all
documentation in pdf. Call one or more preprocessing steps on the source
(this might include lex and yacc). Build the tool. Find all files that
use this tool. Rebuild those too. Oh and everything under revision
control of course.
**) not because they want that. They actually want to force everybody to
use Windows machines. Simply because I cannot work the way they want me
to*** and using a Linux box will buy me a few years to proof they didn't
think through all consequences.
***) nor can the department afford the ridiculous pricing scheme they
try to force on us.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/22/2011 2:28, andrel wrote:
> On 21-4-2011 4:31, Darren New wrote:
>> 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.
>
> I don't own the book. I only saw the page you linked to.
That's why I'm telling you. :-)
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/22/2011 3:09, andrel wrote:
> *) Some changes might trigger a tool to create a tool to be rebuild.
Just so you know, this isn't difficult in Windows. Heck, I don't even have
to write the makefiles myself - the IDE does it. I have lots of data formats
that I wrote my own compiler for that automatically gets compiled before the
data that depends on them gets compiled. Stuff like taking a bunch of
frames for an image, automatically laying them out on a bigger sheet and
storing the boundary information separately with an annotation that the
boundary information depends on the constructed sheet and the constructed
sheet depends on the individual frames and the program depends on the parser
for the boundary information and the individual boundary information files
and etc etc etc. It's not any harder (if not easier) to set up in Windows
than Linux.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/13/2011 10:30 PM, Darren New wrote:
> Am I old, or is it really unprofessional to publish an API and have the
> official documentation for the function call be "go read this guy's blog
> from last June to see an example of how to use this API"? Even if the
> guy is the one that implemented it?
In the military in the 2000-01 timeframe they release the Job
Qualification Standard for my specialty (small computers maintenance),
and many of the training references were to websites. Many of the web
sites did not belong to the military, and some of them were no longer
on-line when I went to read them.
Nice idea, until you try it.
Regards,
John
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 22-4-2011 17:57, Darren New wrote:
> On 4/22/2011 3:09, andrel wrote:
>> *) Some changes might trigger a tool to create a tool to be rebuild.
>
> Just so you know, this isn't difficult in Windows. Heck, I don't even
> have to write the makefiles myself - the IDE does it.
The IDE's that I (superficially) tried when it was relevant (5-10 years
ago) seemed not able to call ctangle before calling the c-compiler (it
simply assumed you were writing C source directly). Let alone call
cweave or mweave (our matlab frontend) to create the docs or mtangle and
leave the results alone. I think some even created a makefile from
scratch everytime, in order to make it impossible to tweak it yourself.
Unfortunately also in that period I simply had no time for a full
investigation, people had problems recording and analysing their data.
And I could modify the matlab sources directly. Always planning to
backport in the WEB files of course...
> I have lots of
> data formats that I wrote my own compiler for that automatically gets
> compiled before the data that depends on them gets compiled. Stuff like
> taking a bunch of frames for an image, automatically laying them out on
> a bigger sheet and storing the boundary information separately with an
> annotation that the boundary information depends on the constructed
> sheet and the constructed sheet depends on the individual frames and the
> program depends on the parser for the boundary information and the
> individual boundary information files and etc etc etc. It's not any
> harder (if not easier) to set up in Windows than Linux.
That might be. In Un*x it is simple a set of scripts and makefiles.
Something I understand. IME in windows it was often hard or impossible
to parse such script files. For some reason I quite often end up wanting
to automatically change them, but that may just be me.
Things might have changed a lot since then. What IDE are you using?
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/23/2011 2:51, andrel wrote:
> Things might have changed a lot since then. What IDE are you using?
Visual Studio 2010 at the moment. It's all XML files.
Indeed, I have a data processor that you can say "this file compiles with
the manifest processor", and each time you run the compile, the manifest
processor parses the makefile to figure out what files go into the final
build and sticks their names into a text file which it adds to the final
build. The sort of thing you'd normally use directory enumeration at runtime
to fetch, if you weren't sandboxed out of the directory access
functionality. So I stick in a file with the name "manifest", say "compile
this with the manifest processor". The manifest processor gets compiled,
then runs and looks at the makefile, pulls out the list of dependencies
marked as "to be copied to the final distribution directory", and stores
that into the manifest file, which then gets copied into the destination
directory also (while leaving the manifest processor behind, mind).
The makefiles are all XML of dependencies and what commands to run, but
there are few if any dependencies in the makefile on actual files per se.
For each directory, there's a list of "these files should be compiled with
those compilers" and a list of "this entire project depends on that antire
project." It's mildly funky because before you can (conveniently) say
"compile manifest.txt with the manifest processor" you must have already
compiled the manifest processor once. Obviously that's an IDE limitation and
not a makefile limitation, tho, since you can delete all the results and
still do the recompile.
But most of the dependency analysis is done by the actual compiler as it
compiles. For example, if you say "I want a house model, and it depends on
the bricks texture and the wood texture", you don't put that information in
the makefile. You put that information in the house model. When the
processor processes the house model, it tells the build system that the
house model depends on the textures, so if you change a texture after you've
built the house, it rebuilds the house too. But you don't do that stuff
manually - that's just silly.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/23/2011 9:42, Darren New wrote:
> So I stick in a file with the name "manifest", say "compile
> this with the manifest processor".
Oh, and if there's parameters specific to that compile (like, whether to
compress images or something), they're represented as properties with an
attribute set (basically, in the "javabean" kind of sense), and the build
system looks at the executable after it's built in order to give the GUI a
mechanism to prompt for which parameters need to be changed. It then records
those parameters into the build file again in XML, and passes them to the
processor when it recompiles anything in that dependency chain.
Overall, a very cool system. It just takes a bit of cooperation from the
compiler to make it all work seamlessly.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 19/04/2011 10:31 AM, Invisible wrote:
> http://questionablecontent.net/view.php?comic=1144
Angus?
The Angus she eventually ended up hooking up with?
Oh, sorry - you guys don't care about that. I forget sometimes...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|
