How to use Python well?
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 Grahn <grahn@ Oo o. . .
\X/ snipabacken.se> O o .
More information about the Python-list