python function parameters, debugging, comments, etc.

[Joel Goldstick]

On Tue, Oct 1, 2013 at 6:54 PM, Chris Friesen <cbf123 at mail.usask.ca> wrote:

>
> I've got a fair bit of programming experience (mostly kernel/POSIX stuff
> in C).  I'm fairly new to python though, and was hoping for some advice.
>
> Given the fact that function parameters do not specify types, when you're
> looking at someone else's code how the heck do you know what is expected
> for a given argument?  (Especially in a nontrivial system where the
> parameter is just passed on to some other function and may not be evaluated
> for several nested function calls.)
>
> Is the recommendation to have comments for each function describing the
> expected args?
>
> I was trying to debug some stuff that someone else wrote.  It turned out
> that the problem was in code like this:
>
>
>
> def rebuild_instance(self, context, instance, image, ...)
>         request_spec = scheduler_utils.build_request_spec(context, image,
> [instance])
>         ...stuff...
>         other_function(...,image,...)
>
>
> where build_request_spec looks like:
>
> def build_request_spec(ctxt, image, instances):
>     ...etc...
>
>
> and it took me a while to realize that rebuild_instance() was being passed
> the image ID (basically just a string), and other_function() was expecting
> the image ID, but build_request_spec() was expecting the actual image
> dictionary.
>
> It also took me a while to realize that that build_request_spec() was
> expecting a list of instances, while rebuild_instance() was passing in a
> single instance.  That one is already fixed in the above code.
>
>
> So what's the recommended way of dealing with stuff like this in larger
> projects with many developers?
>
> Thanks,
> Chris
> --
> https://mail.python.org/mailman/listinfo/python-list
>

One way is to require docstrings (the triple quoted text immediately
following the def line) on your project and set out  requirements for how
to describe the function/method arguments there.  There is a tool call
pydoc that collects docstrings and makes great documentation.

-- 
Joel Goldstick
http://joelgoldstick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20131001/0f943600/attachment.html>