>They are not necessarily exclusive options. >I mean: (intending on) good design is necessary but, if achieved, >it doesn't imply that logging is never necessary.
+1 agreed, regardless of the decision here. >I'd like to recall that logging is a tool primarily for _users_: >it helps them see how their data is handled by "lower" layers. >[Even if the code is fine, some input data might make it seem to >behave strangely, and it is not necessarily the job of the library >developer to figure out how and why this happens. Moreover, in >those cases, a debugger is not always the most productive tool.] Agreed again. But here's where I think it's hard to trace a line between where we should include logging or not. Here's some code from commons-rng: https://github.com/apache/commons-rng/blob/b28f668eea841289020cb89bcae1bd84151100ab/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java#L91 In this line, DiscreteProbabilityCollectionSampler is throwing an exception because the sum of probabilities is greater than 0. The exception is providing meaningful and simple information about the error. And as a user I could want to check if there's anything wrong with the lower level code. In this case, the user will either debug, or modify the code to output some dump data as in commons-imaging. Or just review his data and the conditions of the algorithm without inspecting the code (maths is not really my speciality). While it may be contrived example, I like the design in commons-rng's DiscreteProbabilityCollectionSampler, and would not suggest to include logging there... though I can't really give more meaningful arguments. Now here's some code from commons-imaging: https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/JpegImageParser.java#L233 Here, while reading a JPEG image, the parser complains about the order of segments found in the image. Someone familiar with the format might suspect there's something wrong, and will either use some other tool to validate the segments, or inspect the code. Then s/he will start reading the code, debug, or with the current code of commons-imaging, it is possible to enable debug (setDebug(true) for that class) and see a dump of the current segments. I think in this case we have good exception handling, and the dump method call is unnecessary. While I agree logging the segments and other info here would be helpful, just seeing the message that the segments order is wrong, and on which segment the parser failed, is already quite useful (maybe as useful as knowing that the sum of probabilities in greater than 0 in the commons-rng example?). Not trying to change your opinion on this example. I believe we have had a few discussions around logging here in ASF - not only in commons - and that there is not always a consensus. And said all that, if the majority believes for the case of commons-imaging logging would be good, I'm happy to update the pull request (: what's more important for me is having a 1.0 version that can be released, so that I can keep working on an experiment with the library + IIIF. Cheers Bruno ________________________________ From: Gilles <gil...@harfang.homelinux.org> To: dev@commons.apache.org Sent: Tuesday, 6 February 2018 2:47 AM Subject: Re: [imaging] IMAGING-154 remove Debug class On Mon, 5 Feb 2018 04:41:20 -0800, Otto Fowler wrote: > Maybe Debug should be an interface ( perhaps with the current class > as the > default implementation ) and be passed in optionally? > > > On February 5, 2018 at 07:21:11, Bruno P. Kinoshita ( > brunodepau...@yahoo.com.br.invalid) wrote: > > Hello, > > If memory serves me well, some time ago we had a discussion around > sanselan > & commons-imaging 1.0. One of the issues with commons-imaging 1.0 was > the > Debug class. > > https://issues.apache.org/jira/browse/IMAGING-154 > > I finished the pull request, but Gilles raised an important point, > about > discussing other alternatives first. > > Initially I am against logging in low level libraries, especially > commons > components. But some time ago I had to debug TIFF issues in > commons-imaging, and having the dump methods was a tremendous help. > > > The issue is that some imaging algorithms/processing have a lot of > variables that can be altered. And keeping an eye on all of them in > the > debugger can be quite hard - though not impossible. > > So all in all, now I am more confident to proceed without the Debug > class. > But some users could have a hard time investigating possible issues > in the > library without seeing what's going on within the library. > > IMO, that could be solved with the logging/dump features... or > through a > better design, especially around exception handling/throwing. They are not necessarily exclusive options. I mean: (intending on) good design is necessary but, if achieved, it doesn't imply that logging is never necessary. > The latter is > my preferred approach. Instead of logging, I prefer - whenever > possible - > that low level libraries throw exceptions and let me handle the > logging. I'd like to recall that logging is a tool primarily for _users_: it helps them see how their data is handled by "lower" layers. [Even if the code is fine, some input data might make it seem to behave strangely, and it is not necessarily the job of the library developer to figure out how and why this happens. Moreover, in those cases, a debugger is not always the most productive tool.] > So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a > logging > added to commons-imaging. +1 to remove plain "println" -0 to not provide an helpful alternative In the end, the main developers' and support team should be free to take the decision (IMHO), being fully aware that they deprive themselves from potentially useful tools and additional help. :-) Regards, Gilles > Bruno --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
