Standard header format.

[Matt Austern]

On Jun 8, 2004, at 10:58 AM, Steven T. Hatton wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On Tuesday 08 June 2004 13:24, Phil Edwards wrote:
>> On Tue, Jun 08, 2004 at 09:32:24AM -0400, Steven T. Hatton wrote:
>>> On Tuesday 08 June 2004 01:57, llewelly@xmission.com wrote:
>>>> If the above is intended to inform programmers as the the interface 
>>>> of
>>>>     the library, it belongs in the *documentation*, not in the 
>>>> header
>>>>     files. Most programmers only look at the header files when the
>>>>     documentation is woefully inadequate.
>>>
>>> I haven't taken a scientific poll, but my experience has been most 
>>> C++
>>> programmers with whom I have discussed this issue have been been 
>>> quite
>>> forceful in stating their belief that header files should present 
>>> the API
>>> to the user, and that should serve as a human readable reference for 
>>> the
>>> user of the API.
>>
>> And yet, none of those programmers have ever tried implementing a C++
>> standard library as portable as this one.
>
> First off, you don't know who these people are, or what they have 
> done.  Some
> of them have significant accomplishment to point to.
>
>> The ones who /have/ implemented such a library have spent the last few
>> days telling you that it doesn't work like that.
>>
>> Perhaps some observations and tentative conclusions could be drawn 
>> from
>> this pattern?  Hmmmm...
>
> Yes.  You do not understand what has actually been written.  
> Furthermore, I
> presented supporting evidence for my position which included the API
> documentation and header files from some of the largest C++ projects 
> in the
> world, and showed the clear correspondence between the header file and 
> API
> documentation.  You failed to address that in the least.

Unfortunately, I believe that this discussion is at a dead and and that 
it no
longer serves any useful purpose.

The people who actually implement libstdc++ have explained their reasons
for using implementation techniques that makes the libstdc++ headers 
less
transparent to novices and that make it look less immediately like the 
set of
declarations in the standard.  Whether or not you think those reasons 
are
valid, the people who do the work think so.

If you'd like, you can consider this to be a sign of our incompetence: 
we
aren't smart enough to see how to achieve all of the other design goals
while also writing a library in a form that's suitable as a pedagogical
introduction.  The important thing for you to realize: that isn't going 
to
change just by your telling us that having a library like that would be 
nice.

If you want to see a major reorganization and rewriting of the library
headers, you'll have to do the work.  Learn enough about how the library
is implemented to see why it's done this way, start a discussion (a
detailed discussion, with specific code samples) showing how it could
be done differently, verify that your proposed change wouldn't hurt any
of the other design goals, start a development branch, and start posting
patches.  Yes, that's a lot of work, and it'll require you to learn a 
lot of
things.  But what this discussion should tell you is that nobody else is
going to do that work for you.

			--Matt