messages from pylint - need some reasoning

[GHUM]

Hello,

I am pylinting some software of mine.

Now pylint throws messages, and I know of pylint --help-msg to get
some more text. What is missing out are explanation, WHY some things
are bad, so I am searching for explanations and ways to improve my
code:

Example:
1st) "to many local variables"
I searched big G, and found: many local variables make it harder to
refactor, as all those variables will have to be passed to the
factored-out function. Even worse when the local variables are
mutable, and have to be passed back.


Similiar explanations I am searching for

2nd) "to many statements (in function / method)
okay, shorter functions are easier to grasp. Is there any more
reason?

3rd) space before operators, space after operators, space after ","
that's just readability, or is there some deaper reasoning?

4th) maximum line length
yeah, more then 80 chars suck when outputting to punching cards; but
any 21century reason for this default? (can and have made it higer)


5th) "Too many branches"
"Used when a function or method has too many branches, making it hard
to follow."

So what is the preferred way of repairng this?

Especially if the branches are something like:

if checkforcondition1():
# inlinecode
# to handlecondition1

if checkforcondition2():
# inlinecode
# to handlecondition1

[...]

and multiple conditions can be present at the same time.

Something like mytodolist=[ (tester1, handler1), (tester2,
handler2), ...] and

for tester, handler in mytodolist:
if tester(situation):
handler(situation)

would get rid of the branches; BUT... I cannot see how that is really
easier to follow.


Who can give me some hints to improve my code or arguments to switch
of that warnings?

best wishes,

Harald

 

[Marc 'BlackJack' Rintsch]

Example:
1st) "to many local variables"
I searched big G, and found: many local variables make it harder to
refactor, as all those variables will have to be passed to the
factored-out function. Even worse when the local variables are mutable,
and have to be passed back.

Many local variables can also make it harder to follow what the function
is doing. As rule of thumb a function should do "just one thing", many
variables indicate the function might be doing too much. Or maybe, if
most of the variables belong together somehow, they are candidates for a
class to encapsulate them.

Pylint's default limit is set to 15. So there are more than 15 named
things one has to follow when that message appears.

Similiar explanations I am searching for

2nd) "to many statements (in function / method) okay, shorter functions
are easier to grasp. Is there any more reason?

I think that's *the* reason. Especially in a such a high level language
like Python most things can be expressed quite compact but still
readable. Huge function bodies are an indicator that a function is doing
too much and not just "one thing".

The more code in the function the higher the risk of many nested
indentations and hitting the maximum line length guide.

4th) maximum line length
yeah, more then 80 chars suck when outputting to punching cards; but any
21century reason for this default? (can and have made it higer)

80 characters are still the default width of most terminals and code is
often seen there in diffs or python shell sessions for example. And even
while there is more space on today's monitors, modern IDEs occupy it with
all sorts of function and class browsers, breakpoint windows, online help
etc. so that 80 characters is still a good choice for the editor window.

When posting to mailing lists or newsgroups 80 characters (actually just
75) are the safe limit to ensure that most people can read posted code
without annoying line breaks forced by the reading application. Not so
bad with languages like C because the code still works when copied and
pasted into a text file, but quite catastrophic in languages like Python
that rely on correct indentation.

Last but not least typesetting tells that about 60 to 70 characters are a
good line length to read texts. While program source is usually more
"light" there's still documentation and comments in the source that
should follow the guide lines of typesetting.

5th) "Too many branches"
"Used when a function or method has too many branches, making it hard to
follow."

So what is the preferred way of repairng this?

Breaking it into smaller functions.

Especially if the branches are something like:

if checkforcondition1():
# inlinecode
# to handlecondition1

if checkforcondition2():
# inlinecode
# to handlecondition1

[...]

and multiple conditions can be present at the same time.

Something like mytodolist=[ (tester1, handler1), (tester2, handler2),
...] and

for tester, handler in mytodolist:
if tester(situation):
handler(situation)

would get rid of the branches; BUT... I cannot see how that is really
easier to follow.

Well, you have more, smaller functions that are themselves easier to
follow. And you can/should document each function. Something that you
might not have done (so extensively) in the one function version. Also
the separation of the former "inline code" reduces the possiblity of
names reused for different things in different branches and maybe even
side effects between the branches if they accidentally share objects.

And this refactoring takes an indentation level from the old inline code,
making it easier to keep the lines in the 80 characters limit.

Who can give me some hints to improve my code or arguments to switch of
that warnings?

Try to write the code with less names and statements. Write functions
that do just "one thing" and split big functions into smaller ones.

Ciao,
Marc 'BlackJack' Rintsch