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