Re: [boost] Logging library review results

From: John Torjo (john.groups_at_[hidden])
Date: 2008-03-18 16:52:45

Hi All,
> I read through the submitted reviews and here is a short summary:
>
>   
Thanks to all who contributed. Now I'll know what needs to be improved - 
again ;)

I'd like to formally ask for another review mid-end July.
So, looking for a review manager - again ;)
>
> 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.
>
>   
Yup, will redo, and redo the docs as well.
> 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:
>
>   
Again, I'd like to resubmit, mid-end July.
> * 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.
>   
Got it.
> * 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.
>   
Yes - my problem is that each person seems to have a different opinion 
of what "simple case". However, what I'll do is this:
- have a few simple cases, and write the code for them
- minimize the number of lines I write in order to meet a certain case
- question: what do you think it's a reasonable number of lines, for a 
simple case? I'd go for 5-10 lines of code.

About those simple cases : the problem is that I have my own simple 
cases - which might not be what you want.
So, if you have your great simple case, shout!

On a side-note - I'll make a couple of web pages where I'll split the 
work to be done. Then, you all are most welcome to comment on them.

> * 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 see - ok, basically that's easier for me. So I'm down with that ;)
> * 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.
>   
Got it.
> * Macros usage should be marginally reduced. Documentation should explain 
> how to write them, but not force them as the only solution.
>   
Yup, will do.
> * You may consider supporting lambda like API an one of the alternatives.
>   
That should be possible.
> * Unicode support strategy needs to be fixed
>   
Yes, it will.
> * Documentation require major revision. Obviously I can't put it as a 
> requirement, but my personal recommendation - drop doxigen. IMO you can't 
>   
Well, I'll think about it - however, I really love doxygen. So I guess 
we shouldn't blame the tool for the fact that I messed up the docs.
> have professional documentation based on this format. Plus it's 
> unnecessarily pollute your code. Boostbook and Quickbook are much more 
>   
No offense about Boostbook:
http://www.boost.org/doc/html/boostbook/getting/started.html

But if getting started is so complex, I tend to not use it.
> attractive solutions. Also many reviewers expressed desire for more formal 
> tone in user's guide and reference. (Another personal comment - where did 
>   
About the formal tone in the user's guide/reference - will do.
> you find word "gather" usage as noun? I personally would prefer something 
> like "entry")
>
>   
Where have I used it as a noun?
> 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.
>
>   
Thanks ;)
And it'll happen ;)

Best,
John

-- 
http://John.Torjo.com -- C++ expert
http://blog.torjo.com
... call me only if you want things done right