On Tue, Oct 1, 2013 at 6:54 PM, Chris Friesen <cbf...@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
-- https://mail.python.org/mailman/listinfo/python-list
