Prefer factoring functions and methods out than using comments; the
functoin name is a much better description of the code it contains
than a leading comment on a block; e.g.
# Get data from cache
data = cache.get('foobar')
versus
def GetCacheData():
return cache.get('foobar')
Not terribly obvious in this trivial example, but you save a comment
and improve the readability of the code.
The second bit of advice is to use docstrings in Python when possible,
e.g to document these new methods if necessary:
def GetCacheData(frob=None):
"""Gets data from the local cache instead of from the data store.
The optional string argument frob specifies the name of the cache to
retrieve from, defaulting to the common cache.
"""
if frob:
return cache.get(frob)
else:
return cache.get('common')
which also has the great benefit that things like help() work, and
documentation is easier to generate.
2009/1/12 Sebastian <[email protected]>:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi all,
>
> recently I've started getting into Python and Django programming as
> well as shell scripting.
>
> I was wondering is there any rule or guide on good practice on how to
> comment code?
>
> For me and my current knowledge state, very low I would say :-), I do
> a lot of commenting. sometimes more than one line comments on one line
> code.
> Now I was wondering if I should place the comments before the actual
> code line, after or at the end.
>
> I like commenting in line after the code as it makes the code more
> easy to read - for me...
> But I like commenting lines preceding the code line as it keeps the
> lines itself short...
>
> I think that most would say it comes down to personal preference but I
> was wondering at the same time if there are some rules I should get
> used to right from the start.
>
>
> Cheers,
>
> seb
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.7 (MingW32)
> Comment: http://getfiregpg.org
>
> iD8DBQFJaowNMuBzgG5z7F8RAqZoAJ9Pzw3SRaes6LOdlU4bOqCQSZPFVACghmIG
> NhFonZutl3aBKUneNvtlDOE=
> =fJ7n
> -----END PGP SIGNATURE-----
> --
> SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
> Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
>
--
SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
