2010/10/27 Aurélien Degrémont <aurelien.degremont@cea.fr>
Le 25/10/2010 14:00, nap a écrit :
>>> I passed some pylint passes some months ago, and with a good
>>> configuration it even solve bugs! (it make me saw some = instead of ==
>>> bugs before we use TDD...). But with a standard conf, it warn about
>>> properties used but not created in the __init__ but it's normal with
>>> the properties dict.
>> You can disable some checks if you really think it is a false positive in your case.
>> But I advise do not do so in most of cases.
>> By example, this checks had help me to detect some typos like:
>> def MyClass(object):
>>    def __init__(self):
>>      self._mydata = 1
>>    def inc(self):
>>      self._myata += 1
>> This is correct and will not raise syntax error, but in this case, pylint will tell you that _myata is not declared in
>> __init__, so you can detect your mistake. That's why one must be carefull when disabling some warnings :)
> Yes, but it will warn us about all properties in fact, taht why it
> will be hard to see real errors in it.
If your error message was "Attribute %r defined outside __init__"
This is warning W0201.

Disable it in pylint configuration file:

$ pylint --disable-msg=W0704,W0201 --include-ids=y --generate-rcfile >
Thanks. I think I'll provide a pylintrc with this, so every one can show the code quality with the same base.

>> I also notice that you can transform some of your comment into proper method doc.
> I do not really like docstrings. In fact, it's the separation between
> the function prototype and the real code that annoy me. I like to see
> the comments before the function, so I can see in the prototype and
> code in quite the same lines. But maybe I didn't look enough to others
> Python code for this. I'll try and see if it's so annoying that it was
> for me :)
I'm not a docstrings fan neither, but it is useful. I've always think it
is better to follow a language convention. That way, if a newcomer want
to look at Shinken code, it did not have to learn new convention, if he
knows the Python ways, it will be easy and quick for him to hack Shinken.
Yes. In fact, I think docstrings are the only standard python thing that I'm not happy with.

By the way, Python has its own use of docstrings. This is not only
documentation for developper who browse the source.
Any function docstring could be access through __doc__ attribute.
Various tools have a great use of them. The first one: pydoc

(try 'pydoc str' if you do not know this tool, and then try 'pydoc
anyofshinkenpythonfile' and see the difference).
Other tools can generate nice browsable documentation from the
docstrings, like epydoc (html pydoc-like) by example. 

See PEP-257 for docstring pratices.

For advanced uses, there is PEP-287

I'm not fond of this documentation pratices, but it is good way to
follow the current conventions, it helps a lot.
Yes, but such documentations never allow me to really understand a code. I always prefer a good internal diagram. It should be because I'm a "visual thinking" person (if you want me to understand something, draw it :)  ). I'll look at others projects doc, and see if it's so useful :)

Thanks for your help on this code documentation good practices, it's always better to have a good doc for this :p



Nokia and AT&T present the 2010 Calling All Innovators-North America contest
Create new apps & games for the Nokia N8 for consumers in  U.S. and Canada
$10 million total in prizes - $4M cash, 500 devices, nearly $6M in marketing
Develop with Nokia Qt SDK, Web Runtime, or Java and Publish to Ovi Store
Shinken-devel mailing list