Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!goblin2!goblin.stu.neva.ru!newsfeed.xs4all.nl!newsfeed1.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.000 X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'parameters': 0.04; '(especially': 0.07; 'debug': 0.07; 'nested': 0.07; 'advice.': 0.09; 'arguments': 0.09; 'image,': 0.09; 'instance.': 0.09; 'parameter': 0.09; 'cc:addr:python-list': 0.11; 'python': 0.11; 'def': 0.12; 'cc:name:python list': 0.16; 'collects': 0.16; 'dictionary.': 0.16; 'docstrings': 0.16; 'expecting': 0.16; 'instances,': 0.16; 'line)': 0.16; 'quoted': 0.16; 'subject:etc.': 0.16; 'subject:parameters': 0.16; 'types,': 0.16; "\xc2\xa0i'm": 0.16; 'subject:python': 0.16; 'thanks,': 0.17; 'wrote:': 0.18; 'code.': 0.18; 'bit': 0.19; 'trying': 0.19; 'passing': 0.19; '(the': 0.22; 'programming': 0.22; 'cc:addr:python.org': 0.22; 'instance,': 0.24; 'specify': 0.24; 'fairly': 0.24; 'looks': 0.24; 'cc:2**0': 0.24; "i've": 0.25; 'this:': 0.26; 'header:In-Reply- To:1': 0.27; 'function': 0.29; 'fixed': 0.29; 'chris': 0.29; 'message-id:@mail.gmail.com': 0.30; "i'm": 0.30; 'url:mailman': 0.30; 'code': 0.31; 'comments': 0.31; 'context,': 0.31; 'there.': 0.32; 'stuff': 0.32; 'text': 0.33; 'url:python': 0.33; 'actual': 0.34; 'problem': 0.35; 'tool': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'there': 0.35; 'url:listinfo': 0.36; 'url:org': 0.36; 'requirements': 0.37; 'list': 0.37; 'project': 0.37; 'being': 0.38; 'expected': 0.38; 'skip:o 20': 0.38; 'fact': 0.38; 'pm,': 0.38; 'realize': 0.39; 'though,': 0.39; 'url:mail': 0.40; 'how': 0.40; 'skip:\xc2 10': 0.60; 'new': 0.61; 'took': 0.61; "you're": 0.61; 'great': 0.65; 'hoping': 0.75; "else's": 0.84; 'id,': 0.84; 'joel': 0.91; '2013': 0.98 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=mMa7z8HGdssmVG511mo2WPmvIZIwYyRZVO34UTfpGM8=; b=n7bWB2OJQrDNXoCRmoxMgfxVFD31N3vNJFwNlUkq1Sjd2VWsFsKsX/NQSkonQY8OxD vcrKHqwRY0B3zJHxquj0m8Tq4c+cljXmBiD1r/jWhRjPosou6c35BqgsC4JOs+cm1oqD irCyi9zdsVHS5QlrdnIgFvWGMapB7FEmDB1fxHtLxU8gOrU9iBth1ycXyslviqZRLQr+ j2/1wK3QYJsXTv96xGtpFoGJkIhMfhYA3Q/mCfz6gsrVGmFCF7qwZvsqnkDB+OqsLTq7 goWZwytzuGDAUGK2qEjGhkc2t7JDfyEx0sSjLa0OOwGE5pQAyOLgfN9ZDjNqz+ZRv2T2 WPoQ== MIME-Version: 1.0 X-Received: by 10.58.151.132 with SMTP id uq4mr5022veb.30.1380668591121; Tue, 01 Oct 2013 16:03:11 -0700 (PDT) In-Reply-To: <524B5288.1050709@mail.usask.ca> References: <524B5288.1050709@mail.usask.ca> Date: Tue, 1 Oct 2013 19:03:11 -0400 Subject: Re: python function parameters, debugging, comments, etc. From: Joel Goldstick To: Chris Friesen Content-Type: multipart/alternative; boundary=047d7b6da644ed969c04e7b5f403 Cc: python list X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 136 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1380668599 news.xs4all.nl 15905 [2001:888:2000:d::a6]:59803 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:55249 --047d7b6da644ed969c04e7b5f403 Content-Type: text/plain; charset=UTF-8 On Tue, Oct 1, 2013 at 6:54 PM, Chris Friesen 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 --047d7b6da644ed969c04e7b5f403 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable



On Tue, Oct 1, 2013 at 6:54 PM, Chris Friesen <= ;cbf123@mail.usas= k.ca> wrote:

I've got a fair bit of programming experience (mostly kernel/POSIX stuf= f in C). =C2=A0I'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 expe= cted for a given argument? =C2=A0(Especially in a nontrivial system where t= he parameter is just passed on to some other function and may not be evalua= ted for several nested function calls.)

Is the recommendation to have comments for each function describing the exp= ected args?

I was trying to debug some stuff that someone else wrote. =C2=A0It turned o= ut that the problem was in code like this:



def rebuild_instance(self, context, instance, image, ...)
=C2=A0 =C2=A0 =C2=A0 =C2=A0 request_spec =3D scheduler_utils.build_request_= spec(context, image, [instance])
=C2=A0 =C2=A0 =C2=A0 =C2=A0 ...stuff...
=C2=A0 =C2=A0 =C2=A0 =C2=A0 other_function(...,image,...)


where build_request_spec looks like:

def build_request_spec(ctxt, image, instances):
=C2=A0 =C2=A0 ...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 dicti= onary.

It also took me a while to realize that that build_request_spec() was expec= ting a list of instances, while rebuild_instance() was passing in a single = instance. =C2=A0That 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 w= ay is to require docstrings (the triple quoted text immediately following t= he def line) on your project and set out=C2=A0 requirements for how to desc= ribe the function/method arguments there.=C2=A0 There is a tool call pydoc = that collects docstrings and makes great documentation.

--
--047d7b6da644ed969c04e7b5f403--