[Python-projects] pylint: Separate message category for notes?

[Huurne, Maarten ter]

Hi all,

pylint has message W0511 with the description "Used when a warning note as FIXME or XXX is detected". I think it's very useful to see an overview of such notes that are included in comments in the code. But I'm not sure it should be a warning.

Every time I see something in the code that could be designed better or just feels awkward, I add a "TODO:" note. These are non-critical problems that are not trivial to solve. I often look at these when I'm refactoring code, to remember what the problem with the current design is.

On our code base, the current statistics are like this:
convention: 1
refactor: 22
warning: 190
error: 0

I would like to reach 0 warnings. I have already disabled all rules that create too many false positives, suppressed individual cases of false positives on other rules and also fixed dozens of warnings. The remaining 190 warnings are 14 cases of actual problems in our code and 176 cases of W0511.

I think it would be useful to create a separate category for messages concerning comment notes, so the overview would look like this:
convention: 1
refactor: 22
notes: 176
warning: 14
error: 0

It is not realistic to expect the number of TODOs to ever reach zero: there is always something that could be better in a piece of code, but as they say "better is the enemy of good" and a TODO is a useful compromise to make sure something gets released at all. I only enter TODOs for things that are too much effort to resolve immediately, while other warnings issued by pylint are typically easy to resolve. In fact, I've made it a habit to run pylint on changed files before committing and fix all new issues it finds immediately. So it is realistic to reach and stay at 0 warnings if TODOs are counted separately.

Also, having the notes included in the warning count makes the number harder to interpret. If code contains more warnings, it typically means the code has become worse. However, if a TODO is added in a piece of code, that code has not become worse. In fact, I would say it has become better, since the problems that were already present in the code have been made more visible. We do a full pylint run every night and compare the warning count to that of the previous day; often added TODOs are incorrectly flagged as a regression.

I am considering adding a filter to our pylint post processing script to separate out the W0511 messages. But if there is consensus that it is desirable to have notes as a separate category, I could make the change in pylint itself instead.

Bye,
                                Maarten


________________________________
The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.logilab.org/pipermail/python-projects/attachments/20090318/703fde25/attachment.htm>