How to use Python well?

Jorgen Grahn grahn+nntp at snipabacken.se
Sat Feb 19 01:07:28 CET 2011


On Thu, 2011-02-17, Roy Smith wrote:
> In article <slrnilr5lj.15e.grahn+nntp at frailea.sa.invalid>,
>  Jorgen Grahn <grahn+nntp at snipabacken.se> wrote:
>
>> - Write user documentation and build/installation scripts. Since I'm
>>   on Unix, that means man pages and a Makefile.
>
> Wow, I haven't built a man page in eons.  These days, user documentation 
> for me means good help text for argparse to use.

Perhaps I'm old-fashioned, but all other software I use (on Unix) has
man pages. I /expect/ there to be one. (It's not hard to write a man
page either, if you have a decent one as a template.)

Help texts are better than nothing though (and unlike man pages they
work on Windows too).

> If I need something 
> more than that, I'll write it up in our wiki.

I guess you're working within an organization? Local rules override
personal preferences -- if everyone else is using the wiki, I guess
you must do too.

I have to say though that *not* handling the documentation together
with the source code is harmful.  If source code and documentation
aren't in version control together, they *will* go out of sync.

>> Anyway, I don't feel bad if I don't find any classes at first.
>
> Same here.  I don't usually find a reason to refactor things into 
> classes until I've written the second or third line of code :-)
>
> Somewhat more seriously, the big clue for me that I've got a class 
> hiding in there is when I start having all sorts of globals.  That's 
> usually a sign you've done something wrong.

Or a whole bunch of related arguments to a function, and/or the same
arguments being passed to many functions.

/Jorgen

-- 
  // Jorgen Grahn <grahn@  Oo  o.   .  .
\X/     snipabacken.se>   O  o   .



More information about the Python-list mailing list