messages from pylint - need some reasoning

[Marc 'BlackJack' Rintsch]

On Fri, 17 Oct 2008 00:59:16 -0700, GHUM wrote:

> 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