Velocity Reviews

Velocity Reviews (
-   Perl (
-   -   perlcritic man page (

John Dollar 04-20-2007 01:43 PM

perlcritic man page
Is it just me, or is the man page for perlcritic messed up?

I ask because it's very confusing when it comes to severity.

First, it states for the "-severity N" option:

Severity values are integers ranging from 1 (least severe) to 5 (most
severe). The default is 5.

(which makes you figure it defaults to the MOST SEVERE.)

Then later on, for "-severity NAME":

-severity gentle -severity 5
-severity stern -severity 4
-severity harsh -severity 3
-severity cruel -severity 2
-severity brutal -severity 1

Which is 100% the opposite.

Then for the "-gentle | -stern | -harsh | -cruel | -brutal" options:

These are named shortcuts for setting the "-severity" option. For
example, "-cruel" is equivalent to "-severity 4". to the table above, 4 is "-stern", not "-cruel".

And, of course, the real answer is that the table for "-severity NAME" is the
*ONLY* place that it is correct. However, it DOES default to 5, which is the
LEAST severe.

So, either this is written in some new version of the English language I've
never seen where words change their meanings paragraph to paragraph, or it's
completely confusing/wrong/needs fixing/etc./etc.

thaljef 04-27-2007 06:29 AM

Severity levels in perlcritic
In the early versions, perlcritic only supported the numeric severity levels. But many people said it was hard to remember if "1" was the most critical or least critical setting. So I added the named severity levels to make it a little easier. I didn't realize it at the time, but I had overloaded the meaning of "severity". I agree that it still isn't intuitive, so please allow me to try and explain...

Each violation has a numeric severity level assigned to it (ranging from 1 to 5). Violations with larger numbers are considered more important than those with smaller numbers.

Now when you use a numeric argument with the -severity option, think of it as the minimum level of importance. So "-severity 5" reports only the most important violations.

But when you use a named argument with the -severity option, think of it as the intensity of criticism. So "-severity gentle" also reports only the most important violations.

Essentially, the named and numeric severity levels have an inverse effect. The stronger names equate to smaller numbers, and weaker names equate to larger numbers. But most folks associate greater size with greater strength, so this arrangement can definitely be confusing.

You are absolutely correct about the error in the docs. It should read:
"-cruel" is equivalent to "-severity 2"
Thaks for spotting that. I'll fix it in the next release.

So let me know if that helps clear things up, and I'll try to beef up the documentation as well. If you have suggestions on how to improve the interface, you're totally welcome to send your ideas to the perlcritic team at "dev at perlcritic dot tigris dot org". And thanks for your helpful feedback.



All times are GMT. The time now is 08:31 PM.

Powered by vBulletin®. Copyright ©2000 - 2014, vBulletin Solutions, Inc.
SEO by vBSEO ©2010, Crawlability, Inc.