[Tutor] re: always declaring variables

[Charlie Clark]

On 2003-02-14 at 23:31:13 [+0100], tutor-request@python.org wrote:
> > Yes, Perl has the "my" keyword before the declaration.  I imagine that 
> > this might not get implemented without a fundamental change to the 
> > Python syntax (such as allowing variables to be declared without being 
> > initialized -- might be kind of weird looking and confusing, though).
> 
> I should say that I also use the my as documentation for the variable. 
> That is, they look like this:
> 
> my (@octets) = @_;      # List of octects
> my $octet;              # Octet to process
> my $octetOut;           # Return expanded octet
> my $restOfLine;         # Discription of ip address my $sortKey;          
>   # Concatenated, expanded ipaddress my @answers;            # holds the 
> results
> 
> my @hostEntries;        # Holds a record of data from /etc/hosts
> 
> My hope is that with the additional comments at the begining of the 
> function/subroutine/program the next person to work on the code will have 
> a clue (including me).

"heavens to murgotroyd" where will that lead to?
Naming conventions come up quite often as does commenting and inline 
documentation. They are often very interesting discussions with nuggets 
from the gurus. A rule of thumb is that good pythonic code is largely 
self-explanatory.

The consensus seems to be use names that mean something and relate to each 
other; ie. "octet" and "restofline" are IMHO not a good pair. But I don't 
think commenting variable names is helpful anyway; I for one constantly 
recycle names or transform variables which easily breaks such declarations. 
I also now make extensive use of locally scoped variables where it makes 
sense for me: orthogonally similar functions.

I think it's more important to explain what particular parts are going to 
try to do, ie. a brief commentary at the start of the module as to what it 
aims to do and comments, descriptions of all functions, class methods. 
Functions can carry an optional description and can easily be queried as to 
what variables they expect. More than that doesn't tend to get maintained 
anyway and it's optimistic at best or naive at worst to expect it.

Charlie