Re: [boost] Review of Logging library is in progress

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2008-02-13 13:33:11

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy Rozental
>Sent: 11 February 2008 05:02
>To: boost_at_[hidden]
>Cc: boost-users_at_[hidden]
>Subject: [boost] Review of Logging library is in progress
>
>Here are some questions you might want to answer in your review:
>
>* What is your evaluation of the design?

Appears to meet many of the almost infinitely widely varying requirements.

Many of the reviewers seem to be unwilling to vary their 'essential' requirements, but considering the possible permutations and
combinations, I am unconvinced that their rejections should as absolute as they suggest.

>* What is your evaluation of the implementation?

Seems more complicated than I suspect it really is.

Appears to permit use where efficiency is important.

Although macros provide some neat features, they often impede understanding,
as we have seen with the invaluable Boost.Test written by our Macrophilic Review Manager ;-)

So I recommend presenting examples of how to use this package with 'pure' C++, as well as more slickly using macros. This will also
help quiet the noisy Macrophobes ;-)

This is especially when example macros have inscrutable systemish names like L_.

(I think Boost style is only to use upper case letters for macro names, without trailing _, so I suggest sticking to this as a
recommendation for users macro names.  If they have other conventions, they will use them, but others may assign, and fear, some
deeper meaning from the _.)

Surely it is worth suggesting use of three letters like LOG in an example?

And the #define cries out for a comment line saying "you might like to define a macro that does ...)

'g_l' is not self-explanatory to me. 

Could add_formatter be easier to write and read if add_formatter chained?

(and this namespace information 

using boost::logging::formatter::idx; // index - please!
using boost::logging::formatter::append_newline;
 ...
provided in an .hpp)

so it might read more like:

    g_l()->writer()
      .add_formatter(index() )
      .add_formatter(append_newline() )
      .add_formatter(tag::file_line() )
      .add_formatter(tag::level() );

>* What is your evaluation of the documentation?

Confusing.  Shows every sign of being written by someone who knows too much about it ;-)

Much too chatty in places.

The 1st examples are too difficult.

(The later ones may be too easy - but I haven't got there yet ;-) )

Levels are not mentioned in the 'The Basics'.

>* What is your evaluation of the potential usefulness of the library?

Really Useful.  Boost *MUST* have a logging library.

>* Did you try to use the library? 

No.

>* How much effort did you put into your evaluation? A glance? A quick
>reading?

Another quick reading.

>* Are you knowledgeable about the problem domain?

No.

>And finally, every review should answer this question:
>
>* Do you think the library should be accepted as a Boost library?

Yes. This is a difficult task and this is good enough.

And I think that we should try to get it into much wider real-life use before embarking on too much re-re-review.  The reviewers
usage so far is far too thin, and probably unpresentative, to make detailed judgements.  I favor accepting this pretty much 'as is'
but expecting some quite major revisions of documentation, and perhaps implementation.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]