When you have a C macro more than 300 lines long...
... that takes no arguments
... that you invoke only once

When the only documentation for your library is sample code...
... that doesn't work
... and for which you don't supply source code

When the sample code for doing a conceptually simple operation...
... takes 6000 lines of code
... and 300 global status variables

-- 
   Darren New, San Diego CA, USA (PST)
   "We'd like you to back-port all the changes in 2.0
    back to version 1.0."
   "We've done that already. We call it 2.0."

Post a reply to this message

Darren New wrote:

> When you have a C macro more than 300 lines long...
> ... that takes no arguments
> ... that you invoke only once
> 
> When the only documentation for your library is sample code...
> ... that doesn't work
> ... and for which you don't supply source code
> 
> When the sample code for doing a conceptually simple operation...
> ... takes 6000 lines of code
> ... and 300 global status variables
> 

I don't envy you ...

-- 
~Mike

Post a reply to this message

Darren New <dne### [at] sanrrcom> wrote:
> When the only documentation for your library is sample code...
> ... that doesn't work
> ... and for which you don't supply source code

  What really grinds my gears is the phenomenon during recent years of
libraries appearing on the net which have no documentation, no introductions,
no tutorials and no sample code. The sole "documentation" the library offers
is a doxygen-generated listing of all classes and functions (hundreds of
them), in no logical order (except alphabetical, which is useless) and
usually completely uncommented.

  Probably nobody but the author himself knows how to use the library.

  What's the point?

-- 
                                                          - Warp

Post a reply to this message

Warp <war### [at] tagpovrayorg> wrote:
>   What really grinds my gears is the phenomenon during recent years of
> libraries appearing on the net which have no documentation, no introductions,
> no tutorials and no sample code. The sole "documentation" the library offers
> is a doxygen-generated listing of all classes and functions (hundreds of
> them), in no logical order (except alphabetical, which is useless) and
> usually completely uncommented.
>
>   Probably nobody but the author himself knows how to use the library.
>
>   What's the point?

Same as with contesting for American Idol, or publishing the 1,225,526th Cute
Kitty video on YouTube: Everyone can be a superstar / film maker / library
programmer. Or at least make a fool of himself trying to.

And after all, isn't that the idea of Free Software, that you give back to the
community all code you develop - no matter how useless or redundant it is? :P

Post a reply to this message

Warp wrote:
>   What's the point?

Yes. Yet when you point this out, the answer is invariably "hey, it's free, 
stfu." :-)

Sadly, this is commercial software I'm working with, too.  Bleh!

-- 
   Darren New, San Diego CA, USA (PST)
   "We'd like you to back-port all the changes in 2.0
    back to version 1.0."
   "We've done that already. We call it 2.0."

Post a reply to this message

Le 30/07/2009 20:03, Warp nous fit lire :
> Darren New <dne### [at] sanrrcom> wrote:
>> When the only documentation for your library is sample code...
>> ... that doesn't work
>> ... and for which you don't supply source code
> 
>   What really grinds my gears is the phenomenon during recent years of
> libraries appearing on the net which have no documentation, no introductions,
> no tutorials and no sample code. The sole "documentation" the library offers
> is a doxygen-generated listing of all classes and functions (hundreds of
> them), in no logical order (except alphabetical, which is useless) and
> usually completely uncommented.
> 
>   Probably nobody but the author himself knows how to use the library.
> 
>   What's the point?
> 
Doxygen can be good enough, if used at least correctly.
Beginning the code with a LONG introduction documenting the concepts in use...
You can even embed pictures for doxygen!

But slappy programmers just hope Doxygen will understand the code for them.
Writing with doxygen in mind is easy, but usually it's written without anything on
mind,
and adding doxygen later is just a quick documentation patch, too bad.

Hopefully, the class names are meaning full... (or worse: classes are named with
numbers
or silly name: My_Class_0234 ... hum! Jose_Class_44B Yummy!)

Post a reply to this message

>>   What's the point?
> 
> Yes. Yet when you point this out, the answer is invariably "hey, it's 
> free, stfu." :-)

In Haskell circles, the usual reply is "patches welcome".

In other words, "why don't you do it for me?" (The obvious answer being 
"I'd have to understand how it myself works before I could document it!")

> Sadly, this is commercial software I'm working with, too.  Bleh!

OK, that sucks far more...

Post a reply to this message

> Doxygen can be good enough, if used at least correctly.

Never heard of Doxygen, but if it's anything like Javadoc and Haddock... 
Far too many Haskell libraries have Haddock listings which are useless. 
You know, the kind where the tool produces a list of what functions are 
available, but can't tell you any more than that because nobody has 
written any, you know, *documentation*.

> But slappy programmers just hope Doxygen will understand the code for them.

Slappy programmers? Is that the kind of programmers that make you want 
to slap them? I'll have to remember that one... :-D

Post a reply to this message