On Mar 5, 11:03 am, waTR <r...@devshell.org> wrote:
> Note that more comments doesn't equate to better code. Better code
<CUT>
Amen! code must be readable above ALL else. If you have to make it
unreadable to a beginning pythonista, then you should document
document document!
> My strategy is to write a purpose statement at the beginning of every
> function saying what the function's purpose is. That is more than
> enough. What's more important is producing examples of how to use
> features of the software (web2py book).
<CUT>
I expand on that by adding one more thing, what the function returns
if any.
i.e.:
def dosomethingcool():
""""I do this really cool thing
returns True if cool thing happened, False otherwise.
""""
This way when mucking about interactively, I can dosomethingcool.doc()
and see what it does and what it returns, because I'm forgetful and
constantly lose track of what something does and returns. Especially
true when I move between codebases a lot.
Bringing this back to web2py, I notice web2py doesn't have a ton of
docstrings. It took me several hours to figure out how to get out
from the web2py magic, because none of that stuff is documented at
all. Also tracking down that I really wanted sql.py and not the
obvious dal.py was cumbersomely annoying!! (see previous post about
this.)
With Love,
Tara
--
You received this message because you are subscribed to the Google Groups
"web2py-users" group.
To post to this group, send email to web...@googlegroups.com.
To unsubscribe from this group, send email to
web2py+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/web2py?hl=en.
