[boost] Logging library review results

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2008-03-17 05:54:38

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 --