Re: [gtk-list] Re: DOCUMENTATION (yes, this is shouted)

[KC5TJA <kc5tja topaz axisinternet com>]

On Fri, 21 Aug 1998, Elliot Lee wrote:

> > And this is counting the copyright header and one comment that consists
> > of a row of '*'. How should *anyone* understand what's going on?
> 
> By reading the C code. If you're not able to understand C, then no amount
> of comments will do you good ;-)

This argument is applicable only given a standard method of writing C
code.  Different people, however, have different ways of writing in C.  As
a result, comprehension goes to near zero for most people unfamiliar with
someone's writing style.

I've been writing C for over 15 years.  Yet I can just BARELY understand
what's going on in the Linux source code, and even then, I have to sit and
study the dang thing for hours before I get to ANY kind of understanding.

> Good comments say -why- something is done, and it sounds at this point as
> if you're having trouble understanding -what- is being done.

This is true also, I don't want to spend more time than I have to studying
source code, when I could be using that time to earn money...er...write my
own code... ;)

> The semantics of functions are fairly obvious by reading the header files. 

When functions can return one or more special-case values (e.g., NULL to
indicate a failed operation), this argument falls apart in milliseconds.
Header files are SUPPOSED to do this, but C just gives way too much
freedom for breaking interface specifications.

I recall working with one person's C function, which allocated a bitmap
structure for graphical manipulation.  It returned NULL if it couldn't
allocate a bitmap for the destination.  This is acceptable, since this is
common practice.

But what WASN'T acceptable was that it also returned 0xFFFFFFFF in the
event that 1) the bitmap WAS allocated, and 2) the operation still failed.

This was NOT made apparent by the header files or the function prototype.

> Reading the source code itself might confuse you if you are just wanting
> to use the API and not the internals. 

I think this is the point, though, assuming I understood the original
messages' contents.  And I'd have to agree -- I am considering writing
directly for Xlib rather than using GTK, because GTK isn't well
documented.

> I'm not arguing against documentation! (I try to comment my functions, but
> that is only to balance against its occasional ugliness ;-)  I just think
> that what you specifically want to do can be done easily by reading the
> header files.

I personally have tried this, along with studying the source code.  And
while I *eventually* get it, I just don't have the time to waste doing
this.

Just my opinions... :)

==========================================================================
      KC5TJA/6     |                  -| TEAM DOLPHIN |-
        DM13       |                  Samuel A. Falvo II
    QRP-L #1447    |          http://www.dolphin.openprojects.net
   Oceanside, CA   |......................................................