 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Jim Henderson wrote:
> Yeah, that's a trend that's been around for a while, but I can't say I've
> ever seen it used effectively.
The PHP docs are pretty good at it. But that's because the docs themselves
really tend to answer your questions. They tend to have a decription, what
the parameters mean, sample code, etc. They don't just say "The flooble(zop)
function floobles the provided zop."
The commentary generally had either significant clarifications or sample
code for how to combine different features to get what you want, etc.
>> What's the point of buying proprietary software if you have to document
>> it yourself, or experiment with it to figure out how it works even in
>> normal cases? Sheesh.
>
> That's a pet peeve of mine today (just software documentation in general
> not being very high quality - I remember telling someone about a doc page
> that described a product UI by pointing out things like "the username
> field is where you enter your username" and "the login button is what you
> press to login".
"To insert a column, use the Insert Column menu. But if you needed me to
tell you this, return the software to the store."
"How do you like my documentation so far?"
"I'm only up to the chapter entitled "Duh!""
> Duh, smack me with a 25-story building, I never woulda' guessed that. >:-(
Some of the Microsoft API libraries are starting to have rather sparse
documentation. They have things like "Components.Add(aComponent) adds the
component to the components list." They don't mention "Oh, and by the way,
if the enclosing object has already been initialized, then this will invoke
Initialize() on your component automatically. If the enclosing object hasn't
been initialized, this will invoke Initialize() after the enclosing object
invokes Initialize() but before that invokation returns."
You don't want to initialize things twice, but you also don't get told
if/where it is the system does it for you.
--
Darren New, San Diego CA, USA (PST)
Ada - the programming language trying to avoid
you literally shooting yourself in the foot.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> Some of the Microsoft API libraries are starting to have rather sparse
> documentation. They have things like "Components.Add(aComponent) adds the
> component to the components list." They don't mention "Oh, and by the
> way, if the enclosing object has already been initialized, then this will
> invoke Initialize() on your component automatically. If the enclosing
> object hasn't been initialized, this will invoke Initialize() after the
> enclosing object invokes Initialize() but before that invokation returns."
>
> You don't want to initialize things twice, but you also don't get told
> if/where it is the system does it for you.
Back when I was doing C++/DirectX stuff I remember things like this. The
documentation didn't mention whether objects were getting released by
functions or not. If you used one object to create another, could you then
release the first object? Or when you finally released the second one, did
it release the first one for you?
In the end trial and error using the debug libraries sorted out most leaks.
It had a cool feature where each object was given a number and then when
your program exited it gave a list of numbers that weren't released. You
could then set the debug library to break when an object with that number
was created - it was then obvious (most of the time) what you had
forgotten/not realised to release.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Jim Henderson wrote:
> It seems that companies think "if we put
> a place for people to comment/write/wiki/whatever they'll just
> participate" - and that's generally not the case.
It's not just companies. I lose track of how many Haskell libraries have
"documentation" consisting only of a list of function names and their
type signatures. And when you say "why is there no documentation?" the
answer you get is "patches welcome".
In other words, "if you want to write my documentation for me, I'd be
happy to include it in the next release". I guess distributed version
control makes people lazy.
> That's a pet peeve of mine today - just software documentation in general
> not being very high quality.
If it was only the *documentation* things wouldn't be so bad...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Stephen wrote:
>
> Much more importantly is reason for a wake. ;-)
>
Now why did I think you were going to say that? :-)
We must start thinking about the next PovCon
John
--
Cogito sum,|| wbu### [at] tznvy pbz (rot'ed) || GPG Key Fingerprint:
ergo sum, || These opinions are mine alone, || 0D9BCF4CF1B71CA2F5F7
cogito || others can find their own || BFBBCBC34EDEAEFCE453
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 20/05/2010 10:34 AM, Doctor John wrote:
> Stephen wrote:
>>
>> Much more importantly is reason for a wake. ;-)
>>
> Now why did I think you were going to say that? :-)
> We must start thinking about the next PovCon
>
But I have been thinking about it. ;-)
--
Best Regards,
Stephen
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> does anyone remember gopher? :P
Yes. I used it but once. Ages past.
I was looking for some information on kermit ;-) (the file-transfer-program,
not the frog)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Wed, 19 May 2010 12:53:05 -0700, Darren New wrote:
> Jim Henderson wrote:
>> Yeah, that's a trend that's been around for a while, but I can't say
>> I've ever seen it used effectively.
>
> The PHP docs are pretty good at it. But that's because the docs
> themselves really tend to answer your questions. They tend to have a
> decription, what the parameters mean, sample code, etc. They don't just
> say "The flooble(zop) function floobles the provided zop."
>
> The commentary generally had either significant clarifications or sample
> code for how to combine different features to get what you want, etc.
That's a good point, I've actually used the PHP docs and hadn't thought
about it.
>>> What's the point of buying proprietary software if you have to
>>> document it yourself, or experiment with it to figure out how it works
>>> even in normal cases? Sheesh.
>>
>> That's a pet peeve of mine today (just software documentation in
>> general not being very high quality - I remember telling someone about
>> a doc page that described a product UI by pointing out things like "the
>> username field is where you enter your username" and "the login button
>> is what you press to login".
>
> "To insert a column, use the Insert Column menu. But if you needed me to
> tell you this, return the software to the store."
>
> "How do you like my documentation so far?" "I'm only up to the chapter
> entitled "Duh!""
Yeah, that's the sort of thing I've gotten used to seeing. It's sad...
>> Duh, smack me with a 25-story building, I never woulda' guessed that.
>> >:-(
>
> Some of the Microsoft API libraries are starting to have rather sparse
> documentation. They have things like "Components.Add(aComponent) adds
> the component to the components list." They don't mention "Oh, and by
> the way, if the enclosing object has already been initialized, then this
> will invoke Initialize() on your component automatically. If the
> enclosing object hasn't been initialized, this will invoke Initialize()
> after the enclosing object invokes Initialize() but before that
> invokation returns."
>
> You don't want to initialize things twice, but you also don't get told
> if/where it is the system does it for you.
That's useful. (not)
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Thu, 20 May 2010 09:26:08 +0100, Invisible wrote:
> Jim Henderson wrote:
>
>> It seems that companies think "if we put a place for people to
>> comment/write/wiki/whatever they'll just participate" - and that's
>> generally not the case.
>
> It's not just companies. I lose track of how many Haskell libraries have
> "documentation" consisting only of a list of function names and their
> type signatures. And when you say "why is there no documentation?" the
> answer you get is "patches welcome".
>
> In other words, "if you want to write my documentation for me, I'd be
> happy to include it in the next release". I guess distributed version
> control makes people lazy.
Well, in the OSS world, there tends to be a focus on code rather than on
documenting it. There are some areas in both OSS and commercial software
where documentation is pretty good - it's just rare.
>> That's a pet peeve of mine today - just software documentation in
>> general not being very high quality.
>
> If it was only the *documentation* things wouldn't be so bad...
Documentation is relatively easy to do; software is far more complex.
Most people expect bugs in software because of the complexity; but most
people expect documentation that's useful.
Jim
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
scott wrote:
>> You don't want to initialize things twice, but you also don't get told
>> if/where it is the system does it for you.
And it turns out that if you add the component before you initialize the
game, then the component manager thing initializes all those added
components. If you add the component after you initialize the game, the
component gets initialized as you add it. *But* if you add the component in
the game's Initialize() function, the component never gets initialized. It
does, however, get deinitialized, so I'm pretty sure that's a bug and not
just something I'm doing wrong.
> Back when I was doing C++/DirectX stuff I remember things like this.
> The documentation didn't mention whether objects were getting released
> by functions or not. If you used one object to create another, could
> you then release the first object? Or when you finally released the
> second one, did it release the first one for you?
And that is the joy of GC. That's exactly the kind of example I use to
explain why Alan Kay says that GC is required for an OO system. Otherwise
you have to know the internals of the classes, and in particular whether
they copy or reference the instances you pass to them.
> In the end trial and error using the debug libraries sorted out most
> leaks. It had a cool feature where each object was given a number and
> then when your program exited it gave a list of numbers that weren't
> released. You could then set the debug library to break when an object
> with that number was created - it was then obvious (most of the time)
> what you had forgotten/not realised to release.
Yeah, stuff like that is cool. It can work OK when you have good tools.
When your destination platform is too small to hold a debugger, you can be
rather screwed.
--
Darren New, San Diego CA, USA (PST)
Ada - the programming language trying to avoid
you literally shooting yourself in the foot.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Jim Henderson wrote:
> Well, in the OSS world, there tends to be a focus on code rather than on
> documenting it.
Unfortunately, most people don't seem to realize that a *library* with no
documentation is worse than useless.
--
Darren New, San Diego CA, USA (PST)
Ada - the programming language trying to avoid
you literally shooting yourself in the foot.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|
