python function parameters, debugging, comments, etc.

[Chris Friesen]

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