Logging library review results
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 --
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
John Torjo wrote:
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.
My example of a simple case might be something like this: I want to log to a file, with three levels of logging. So I might want to do the following (just an example! Not trying to mandate an interface or anything): #include <boost/log.hpp> using namespace boost; using namespace boost::log; log<to_file<some_template_tricks>> my_log(warning); // some function { my_log(error)<<"Error! Something went wrong!"; } The some_template_tricks is just there because you can't put string literals in a template - if we had to make our own streams and template them, that would be okay. And the use of warning and error are just error-checking conditions - if I construct it with warning as the parameter, then only stuff that's a warning level or more serious can be logged. I would define a concept to indicate a set of conditions and allow those to be passed in as a template parameter. If you look at the kind of genericism in multi_index, that is the kind of thing I'd like to see more of - lots of stuff that's easily avoided if you don't need it, but generic and powerful if you do. As for the documentation, I think that Doxygen is fine, but things need to be sorted better, and the reuse of identifiers in lots of different namespaces definitely hurts. Especially when it comes to linkage - you have names in the documentation that are mislinked because you have them in 4 different namespaces and Doxygen can't figure out which one you are trying to refer to. Long names aren't too much of an issue, particularly in types. If something can be typedefed away, then it makes stuff look good and has the nice scoping to go with it. I really want to see a logging library in boost, as boost is frequently the first place I look for a nice, reliable, portable library. It's definitely something I would like to see in the future, because I really want to have a nice interface that I don't end up reinventing every time I start a new project. Sean
Sean Hunt <rideau3 <at> gmail.com> writes:
I want to log to a file, with three levels of logging. So I might want to do the following (just an example! Not trying to mandate an interface or anything):
#include <boost/log.hpp>
using namespace boost; using namespace boost::log;
log<to_file<some_template_tricks>> my_log(warning);
Why would you want compile time configuration? I agree with one of the reviewers: in majority of the cases the only things that needs to be defined at compile time is message/entry type and filter type. How is it better than : regular_log my_log( "thresholdlevel=warning;file=abc.txt" ); One thing that might be defined at compile time is level: log_with_tag<level> my_log( "thresholdlevel=warning;file=abc.txt" ); In general logging should'n use compile time sparcely and prefer interfaces. The only preformance critical part is filterring. Formatting and destination optimization are pointless IMO. Gennadiy
participants (3)
-
Gennadiy Rozental -
John Torjo -
Sean Hunt