You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-dev@logging.apache.org by Gary Gregory <ga...@gmail.com> on 2012/09/24 23:36:22 UTC
API names like org.apache.logging.log4j.Logger.catching(Throwable)
Hi All:
I've started porting a project from 1.2.16 to 2.0.
I find the Logger.catching() API name to be rather poor. I can't recall
seeing APIs that say do-"ing" something. APIs usually just "do". IMO, the
fact that the API was can be called from a catch clause should not create
the need to call the API catching.
So, "log" would be better IMO, because the /Logger/ logs the exception. The
Javadoc is lacking here, what level is used?
One way I like to think about API names and Javadoc is to see how they both
read. I assume we are all using the active voice pattern for Javadoc of
course ;) I like it when I see, for example, an API called runFast() and
the Javadoc says "Runs fast.".
Which is why the catching() name is that much the lamer ;) IMO.
Tangent:
This is further (slightly) confusing because there are FATAL, ERROR, DEBUG
(and so on) Levels which match up with fatal(), error() and debug()
methods. There is no CATCHING level of course ;)
Which brings up the bigger issue of API names and what the proper name
should be. Usually, APIs /do/ something, using a verb, like log() or
warn(). An better active verb API would be inform() for INFO. Luckily we do
have already warn() for WARN, debug() for DEBUG, trace() for TRACE. Where
there is no great choice is for FATAL, where we have fatal() today. So we
are just lucky that all levels except INFO and FATAL match up with
verbs.The flip side is that it having API names match the level names
follows he KISS principle :) which, in the end, I like better in this case.
Gary
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: API names like org.apache.logging.log4j.Logger.catching(Throwable)
Posted by Gary Gregory <ga...@gmail.com>.
On Mon, Sep 24, 2012 at 6:06 PM, Ralph Goers <ra...@dslextreme.com>wrote:
> See http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#throwing(java.lang.String,
> java.lang.String, java.lang.Throwable) as this is where these names
> originated from. Logback has variations on these at
> http://www.slf4j.org/apidocs/org/slf4j/ext/XLogger.html#catching(java.lang.Throwable).
> So to make implementing compatibility with these easy it is better to have
> them. Furthermore, many of my colleagues like using these methods as they
> seem to be intuitively obvious as to why they are there, so I am inclined
> to keep them.
>
> It has already been reported that the documentation says the default
> method is logging at Debug while the documentation says it is Error and I
> will fix that.
>
Thank you for the history Ralph. I still do not like it ;) but I understand
it.
Gary
>
> Ralph
>
>
>
>
> On Sep 24, 2012, at 2:36 PM, Gary Gregory wrote:
>
> Hi All:
>
> I've started porting a project from 1.2.16 to 2.0.
>
> I find the Logger.catching() API name to be rather poor. I can't recall
> seeing APIs that say do-"ing" something. APIs usually just "do". IMO, the
> fact that the API was can be called from a catch clause should not create
> the need to call the API catching.
>
> So, "log" would be better IMO, because the /Logger/ logs the exception.
> The Javadoc is lacking here, what level is used?
>
> One way I like to think about API names and Javadoc is to see how they
> both read. I assume we are all using the active voice pattern for Javadoc
> of course ;) I like it when I see, for example, an API called runFast() and
> the Javadoc says "Runs fast.".
>
> Which is why the catching() name is that much the lamer ;) IMO.
>
> Tangent:
>
> This is further (slightly) confusing because there are FATAL, ERROR, DEBUG
> (and so on) Levels which match up with fatal(), error() and debug()
> methods. There is no CATCHING level of course ;)
>
> Which brings up the bigger issue of API names and what the proper name
> should be. Usually, APIs /do/ something, using a verb, like log() or
> warn(). An better active verb API would be inform() for INFO. Luckily we do
> have already warn() for WARN, debug() for DEBUG, trace() for TRACE. Where
> there is no great choice is for FATAL, where we have fatal() today. So we
> are just lucky that all levels except INFO and FATAL match up with
> verbs.The flip side is that it having API names match the level names
> follows he KISS principle :) which, in the end, I like better in this case.
>
> Gary
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> JUnit in Action, 2nd Ed: <http://goog_1249600977/>http://bit.ly/ECvg0
> Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory
>
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: API names like org.apache.logging.log4j.Logger.catching(Throwable)
Posted by Ralph Goers <ra...@dslextreme.com>.
See http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#throwing(java.lang.String, java.lang.String, java.lang.Throwable) as this is where these names originated from. Logback has variations on these at http://www.slf4j.org/apidocs/org/slf4j/ext/XLogger.html#catching(java.lang.Throwable). So to make implementing compatibility with these easy it is better to have them. Furthermore, many of my colleagues like using these methods as they seem to be intuitively obvious as to why they are there, so I am inclined to keep them.
It has already been reported that the documentation says the default method is logging at Debug while the documentation says it is Error and I will fix that.
Ralph
On Sep 24, 2012, at 2:36 PM, Gary Gregory wrote:
> Hi All:
>
> I've started porting a project from 1.2.16 to 2.0.
>
> I find the Logger.catching() API name to be rather poor. I can't recall seeing APIs that say do-"ing" something. APIs usually just "do". IMO, the fact that the API was can be called from a catch clause should not create the need to call the API catching.
>
> So, "log" would be better IMO, because the /Logger/ logs the exception. The Javadoc is lacking here, what level is used?
>
> One way I like to think about API names and Javadoc is to see how they both read. I assume we are all using the active voice pattern for Javadoc of course ;) I like it when I see, for example, an API called runFast() and the Javadoc says "Runs fast.".
>
> Which is why the catching() name is that much the lamer ;) IMO.
>
> Tangent:
>
> This is further (slightly) confusing because there are FATAL, ERROR, DEBUG (and so on) Levels which match up with fatal(), error() and debug() methods. There is no CATCHING level of course ;)
>
> Which brings up the bigger issue of API names and what the proper name should be. Usually, APIs /do/ something, using a verb, like log() or warn(). An better active verb API would be inform() for INFO. Luckily we do have already warn() for WARN, debug() for DEBUG, trace() for TRACE. Where there is no great choice is for FATAL, where we have fatal() today. So we are just lucky that all levels except INFO and FATAL match up with verbs.The flip side is that it having API names match the level names follows he KISS principle :) which, in the end, I like better in this case.
>
> Gary
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> JUnit in Action, 2nd Ed: http://bit.ly/ECvg0
> Spring Batch in Action: http://bit.ly/bqpbCK
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory