[Boost-announce] Logging library review results

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2008-03-17 06:01:58

This is unfortunately delayed results review of Logging library submitted by

John Torjo.

I read through the submitted reviews and here is a short summary:

- 2 Tom Brinkman         | evaluate it again, if a more boost friendly,
lambda style public interface is present
+ 7 Steven Watanabe    | all the issues with destructors and exceptions
absolutely must be fixed
+ 7 Vadim                     | with some improvements to documentation and
ease-of-use
- 0 Phil Endecott            | not in its current form
+ 9 Jurko Gospodnetic   | seems good enough
- 3 Jamie Allsop             | changes that are needed are too numerous to
warrant a 'yes and tidy-up' vote
- 2 Christian Holmquist   | the documentation is written with other
scenarios in mind
- 4 Sean Hunt                 | approach is a little too generic and forces
the user to jump through hoops
+ 9 Arnstein Ressem       | compiler and valgrind warnings has to be fixed
before submission
+ 6 Loic Joly                  | yes, knowing this library will probably
evolve anyway
+ 7 Paul A Pristow         | expecting some quite major revisions of
documentation, and perhaps implementation
- 3 Amit                         | Not in its current form. with some
changes library would have support
-1/2 Paul Bexter             | spread too thin
- 4 Scott Woods            | logging facility should be targeted slightly
differently
+ 10 Bruce Sharpe         | need exactly this functionality
- 1 Andrey Semashev     | expect something different and more elaborate from

the logging library

(The number after the vote is my own estimation of review vote in 0-10
grade). Paul Bexter did not express clear vote, but submitted an opinion
supporting Amit position.

In the end we came to 8 negative 7 positive votes with average 4.9 grade.
Essentially opinions split right in a middle. Oh, how familiar these days ;)

I must say this puts me in a quite a spot. The library obviously has great
potential, but quite unacceptable by many in it's current form. While
praising it's flexibility in many aspects, the reviewers expressed wide
variety of serious concerns regarding design, implementation and
documentation.

Well, I can't delay it any more. ;) Under the circumstances, I prefer to err

on a side of caution.

The logging library submission is NOT accepted in it's current form.

My biggest concern, as many others expressed here before, is that we do need

the logging library. So I can't be any more encouraging to John to resubmit
an updated version for review within any reasonably short time, once issues
brought during review are addressed. I am not going to list all the issues
here - you will need to look through quite detailed reviews, but I want to
emphasize most prominent ones:

* The library would gain from clean separation of framework and solution.
What I mean here is that there should be separate
layer which defines only generic concepts and another layer for specific
solutions provided by library. My personal suggestion is to use layered
design, where each layer is more feature-rich, but more targeted.
* Library should support wide variety of "simple cases" out of the box and
with minimal efforts required by users. *Each* usage scenario should be well

documented and supported by example.
* Library shouldn't try to be too smart. All optimizations and advanced
features should be eliminated. At least not in a review version. This
includes any kind of optimized strings or scenario based log selection.
Later on you may start adding them based on user input.
* I recommend to start some kind of pool for simple/common cases on the dev
list before you jump to support them. Library should clearly state that
other more advanced usage cases are supportable as well. The same
recommendation applies to the general set of supported features by the
library out of the box.
* Macros usage should be marginally reduced. Documentation should explain
how to write them, but not force them as the only solution.
* You may consider supporting lambda like API an one of the alternatives.
* Unicode support strategy needs to be fixed
* Documentation require major revision. Obviously I can't put it as a
requirement, but my personal recommendation - drop doxigen. IMO you can't
have professional documentation based on this format. Plus it's
unnecessarily pollute your code. Boostbook and Quickbook are much more
attractive solutions. Also many reviewers expressed desire for more formal
tone in user's guide and reference. (Another personal comment - where did
you find word "gather" usage as noun? I personally would prefer something
like "entry")

Yet again I'd like to express our gratitude to the John for his efforts and
hopes that he'll be able to see this library though to the eventual success.

It has great potential.

Gennadiy Rozental
-- Review Manager --