Review of Logging library is in progress
Hi, To those who managed to miss this very exciting submission, I would like to encourage to find some time to invest into reviewing it. Admitedly this is very open-bound problem domain and many people have different opinions on design requirements and possible interfaces. It makes it even more important to get large number of reviewers representing wide spectrum of users base. Please let me know about any time constrains, I might try to arange for the review period extension. Here is a copy of an oroginal announcements: *Description/Motivation:* Applications today are becoming increasingly complex. Part of making them easier to develop/maintain is to do logging. Logging allows you to see what happened in your application. It can be a great help when debugging and/or testing it. The great thing about logging is that you can use it on systems in production and/or in use - if an error occurs, by examining the log, you can get a picture of where the problem is. Good logging is mandatory in support projects, you simply can't live without it. Used properly, logging is a very powerful tool. Besides aiding debugging/ testing, it can also show you how your application is used (which modules, etc.), how time-consuming certain parts of your program are, how much bandwidth your application consumes, etc. - it's up to you how much information you log, and where. *Online docs:* http://torjo.com/log2/doc/html *Download:* Package for download is available here: http://torjo.com/code/log2.zip (version v0.22.7 is targeted for review) or you can get the library from svn http://svn.boost.org/svn/boost/sandbox/logging/ *Compilation:* The Boost Logging Lib has been tested with the following compilers: VC 2005 VC 2003 gcc 3.4.2 gcc 4.1 Compiling using bjam is covered here: http://torjo.com/log2/doc/html/miscelaneous.html#misc_bjam What to include in Review Comments ================================== Your comments may be brief or lengthy, but basically the Review Manager needs your evaluation of the library. If you identify problems along the way, please note if they are minor, serious, or showstoppers. Here are some questions you might want to answer in your review: * What is your evaluation of the design? * What is your evaluation of the implementation? * What is your evaluation of the documentation? * What is your evaluation of the potential usefulness of the library? * Did you try to use the library? With what compiler? Did you have any problems? * How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? * Are you knowledgeable about the problem domain? And finally, every review should answer this question: * Do you think the library should be accepted as a Boost library? Be sure to say this explicitly so that your other comments don't obscure your overall opinion. Gennadiy Rozental - Review Manager -
on Mon Feb 11 2008, "Gennadiy Rozental" <rogeeff-AT-gmail.com> wrote:
Hi,
To those who managed to miss this very exciting submission, I would like to encourage to find some time to invest into reviewing it. Admitedly this is very open-bound problem domain and many people have different opinions on design requirements and possible interfaces. It makes it even more important to get large number of reviewers representing wide spectrum of users base. Please let me know about any time constrains, I might try to arange for the review period extension.
You left out a very important piece of information: when is the review deadline? -- Dave Abrahams Boost Consulting http://boost-consulting.com
Gennadiy Rozental a écrit : I have not been able to devote enough time to make a full length review. So this is more of a feeling than of a review. Fell free to ignome my vote accordingly.
* What is your evaluation of the design?
It seems to be a little bit too raw to be usable by the unwary user. Some eviewers have complained about the use of macro. Loggoing is IMO one of the few places where macro usage is a good thing. There are some places where logging won't get acceptance if it cannot be demonstrated the it can be zero cost when de-activated (even if all odds are that it will finally not be de-activated). It is a psychological problem as well as a technical problem, but it is important.
* What is your evaluation of the implementation?
I did not look at the implementation.
* What is your evaluation of the documentation?
The learning curve is too steep. Is it the fault of the documentation or of the library ? I do not know.
* What is your evaluation of the potential usefulness of the library?
Huge.
* Did you try to use the library? With what compiler? Did you have any problems?
Not that version. I use previous version successfully with visual C++, but this version sees to be so much appart that I do not know if this is relevant at all.
* How much effort did you put into your evaluation? A glance? A quick reading? In-depth study?
Only read the doc, about 1h spent
* Are you knowledgeable about the problem domain?
Only as well as any programmer should be.
And finally, every review should answer this question:
* Do you think the library should be accepted as a Boost library I would like to agree with other reviewers: Logging is so vast a project that anyone want it own special options that fit its particular needs. I think the review of the previous version of the library suffered the same problem. This has led John Torjo to write the swiss army knife of logging, and still, some people miss miss some options... My opinion is that a logging library is so much needed that I do not really care if it is not perfect, as long as it is usable & extendable.
What I miss most is simplicity. I would really appreciate is a basig logging configuration was provided for a quickstart. By basic, I mean something that allow code such a this : - Log onto a file - Set the log level (at compile time or at run time) - Log using iostream syntax - Initialization should be a one-liner in user code. It can allow more, but the one-liner stuff is important. I don't knows if there if a fast track second chance review process for a library. If there is one, I think it would be better to wait a few weeks and have another review. Otherwise, I vote yes, knowing this library will probably evolve anyway after the many remarks done during the review. -- Loïc Joly
Hi Loïc, Thanks for the review.
* What is your evaluation of the design?
It seems to be a little bit too raw to be usable by the unwary user. Some eviewers have complained about the use of macro. Loggoing is IMO one of the few places where macro usage is a good thing. There are some
I do agree, I did probably use too many macros though... Anyway, will do my best to remove most of them
The learning curve is too steep. Is it the fault of the documentation or of the library ? I do not know.
A bit of both :) Will fix.
And finally, every review should answer this question:
* Do you think the library should be accepted as a Boost library
I would like to agree with other reviewers: Logging is so vast a project that anyone want it own special options that fit its particular needs. I think the review of the previous version of the library suffered the same problem. This has led John Torjo to write the swiss army knife of logging, and still, some people miss miss some options... My opinion is
Exactly :) v1 - simple , not flexible enough v2 - very flexible, but not simple enough
that a logging library is so much needed that I do not really care if it is not perfect, as long as it is usable & extendable.
What I miss most is simplicity. I would really appreciate is a basig logging configuration was provided for a quickstart. By basic, I mean something that allow code such a this : - Log onto a file - Set the log level (at compile time or at run time) - Log using iostream syntax - Initialization should be a one-liner in user code.
Basically I added this after the review started - the boost/logging/out_of_the_box directory.
It can allow more, but the one-liner stuff is important.
Seems so :)
I don't knows if there if a fast track second chance review process for a library. If there is one, I think it would be better to wait a few weeks and have another review. Otherwise, I vote yes, knowing this library will probably evolve anyway after the many remarks done during the review.
Thanks! Best, John -- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 11 February 2008 05:02 To: boost@lists.boost.org Cc: boost-users@lists.boost.org 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 +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
Hi Paul, Thanks for the positive review! (just now, when I so got used to the negative ones :))
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.
Thanks :)
* What is your evaluation of the implementation?
Seems more complicated than I suspect it really is.
Appears to permit use where efficiency is important.
Oh yes!
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 ;-)
As said, I will remove most of them. And one or two remaining - I'll make them optional.
This is especially when example macros have inscrutable systemish names like L_.
The only reason for the ending _ was that I wanted a very short name, and one letter seemed too short :)
Surely it is worth suggesting use of three letters like LOG in an example?
Will do.
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.
Got it, will use better naming.
Could add_formatter be easier to write and read if add_formatter chained?
(and this namespace information
using boost::logging::formatter::idx; // index - please!
Yup, will change :)
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() );
Sure, not a problem!
* 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.
Yup, got that - will update.
The 1st examples are too difficult.
(The later ones may be too easy - but I haven't got there yet ;-) )
Will make them easier.
Levels are not mentioned in the 'The Basics'.
Will do.
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.
Thanks, will happen! Best, John -- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right
participants (5)
-
David Abrahams -
Gennadiy Rozental -
John Torjo -
Loïc Joly -
Paul A Bristow