[boost] Re: Changes with new release

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-07-21 22:56:47

Gennaro Prota wrote:
> On Sun, 20 Jul 2003 17:39:05 -0400, "Edward Diener"
> <eddielee_at_[hidden]> wrote:
>
>>>> If I were a
>>>> library implementor, whether Boost or otherwise, I would want to
>>>> explain my ideas to the outside world as a way of promoting good
>>>> technology.
>>>
>>> Ahehm... :-)
>>
>> An extra 'h' maybe <g>. Or is it just extra phlegm that got stuck in
>> your throat when you typed it <g><g>.
>
> I'm not sure what you are hinting at, anyway I just felt a little
> ridiculous at thinking I was documenting/promoting "good technology".

I missed the mark. I meant to write "phleghm", in which I was trying to be
linguistically funny and clever about your spelling of 'ahehm' for 'ahem',
and at the same time actually make semantic sense.

And why would you feel ridiculous that you are promoting good "technology" ?
I certainly think that Boost is good technology and I certainly see it as a
worthy thing for Boost implementors to promote it through normal non-code
methods. Is it too grandiose an idea that Boost is promoting good
"technology" ?

>
>
>> Actually I am quite serious with my preceding paragraph. I have
>> never quite understand why so many good, and often brilliant
>> programmers, take it so hard when others suggest that they document
>> what they do in easily understandable sentences. There must be
>> something wrong in the educational systems of the countries from
>> which most programmers come when they can not, or do not, want to
>> write clearly.
>
> Wow, what an energetic paragraph :-) Honestly, after reading this I
> went reading the whole thread (which I didn't before) looking for some
> negative answer that could justify your impression, but didn't find
> any. I see that Peter, for instance, agrees with the idea. Also,
> lexical_cast has a concise and clear summary of the changes.

I meant no derogatory remark with that paragraph. It is just that when
programmers are asked to document anything outside of the actual code they
write they seem to inevitably take offense at it as if the asker has no
right to even suggest that they might do that. To me the inability, or
unwillingness, to use language to explain one's ideas or communicate what
one has done to other people bespeaks a failure in education.

>
> Of course it's true that many libraries don't have it, and I agree
> that it is something users may have a need for, if nothing else to
> decide whether upgrading or not. Basically this requires a little
> preventive "organization" on the authors' part, because when it's time
> to write the change section you are likely to not remember all the
> significant changes you have done; and, of course, you don't write the
> section _while_ doing the changes, because should they reveal
> inadequate you have wasted time both with the code and with the
> documentation

I think it takes very little time writing down general changes. My original
post was not asking developers to write down specific changes but to
generalize the major points of difference from one release to the next.
Peter Dimov's suggestion that a CVS change log be generated is great, but
that is not really what I was suggestion as change documentation. Something
more along the lines of:

1) Class such-and-such has changed member function so-and-so to take
such-and-such parameter instead of so-and-so parameter.

and other items along these lines which may affect end-users.

> (this "I don't remember" issue is not a joke... due to
> lack of time my changes to dynamic_bitset spans about one year;
> fortunately I've noted the rationale for almost everything I've done
> because I did know that then Jeremy would have asked me about it, but
> people who are the only authors of their library could not do the
> same). Also, filtering the "internal" changes from changes that could
> interest the user is quite a work too (it also depends on the level of
> the user, of course. And you have to make a choice, based on your
> personal idea of the inexistent "average" user - in the end you will
> probably collect many of these little improvements under a generic
> "several bug fixes" entry).

It's up to the implementor to specify what has changed and decide what the
end-user may want to know. But I really don't see it as overwhelming.

>
> Summarizing, I agree with you that the work should be done but don't
> underestimate it: if you take it seriously it requires time.

Everything takes time but I think the time spent for this is worth it. It is
the same idea about documenting functionality so that others can use one's
programming ideas. It is a worthy thing for an implementor to be willing to
communicate one's ideas and make it easier for an end-user to work with
those ideas.