Path: csiph.com!usenet.pasdenom.info!gegeweb.org!usenet-fr.net!nerim.net!novso.com!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.004 X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'classes,': 0.05; 'run- time': 0.05; 'advice.': 0.09; 'pep': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'referenced': 0.09; 'api': 0.11; 'python': 0.11; '(when': 0.16; 'docstrings': 0.16; 'finney': 0.16; 'gandhi': 0.16; 'magic': 0.16; 'modules,': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'subject:etc.': 0.16; 'subject:parameters': 0.16; 'url:peps': 0.16; 'subject:python': 0.16; 'bit': 0.19; 'programming': 0.22; 'header:User-Agent:1': 0.23; 'url:dev': 0.24; 'fairly': 0.24; "i've": 0.25; 'source': 0.25; 'header:X-Complaints-To:1': 0.27; 'function': 0.29; 'chris': 0.29; "i'm": 0.30; 'asked': 0.31; 'code': 0.31; 'comments': 0.31; 'team.': 0.31; 'documenting': 0.31; 'writes:': 0.31; 'stuff': 0.32; 'url:python': 0.33; 'standards': 0.33; 'but': 0.35; 'there': 0.35; 'thanks': 0.36; 'url:org': 0.36; 'expected': 0.38; 'ben': 0.38; 'to:addr:python-list': 0.38; 'though,': 0.39; 'to:addr:python.org': 0.39; 'enough': 0.39; 'received:org': 0.40; 'how': 0.40; 'above,': 0.60; 'mentioned': 0.61; 'new': 0.61; 'url:3': 0.61; 'discuss': 0.62; 'information': 0.63; 'such': 0.63; 'choose': 0.64; 'taking': 0.65; 'skip:\xe2 10': 0.65; 'improvement.': 0.68; 'hoping': 0.75; '\xe2\x80\x93': 0.77; '8bit%:46': 0.78; '*and*': 0.84; 'western': 0.86 X-Injected-Via-Gmane: http://gmane.org/ To: python-list@python.org From: Ben Finney Subject: Re: python function parameters, debugging, comments, etc. Date: Wed, 02 Oct 2013 11:51:09 +1000 References: <524B5288.1050709@mail.usask.ca> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Gmane-NNTP-Posting-Host: rasputin.madmonks.org X-Public-Key-ID: 0xAC128405 X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35 4855 B8B2 4C06 AC12 8405 X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-gpg.asc X-Post-From: Ben Finney User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux) Cancel-Lock: sha1:Ytk9Lb6d7DklwdXMNU/XXuaORY0= 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: 38 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1380678683 news.xs4all.nl 15882 [2001:888:2000:d::a6]:54676 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:55263 Chris Friesen writes: > 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. Welcome! Thanks for taking the practice of programming seriously enough to seek improvement. > Is the recommendation to have comments for each function describing > the expected args? Not quite; we don't use comments for that purpose, but docstrings . Python docstrings allow documenting the API of modules, classes, and functions, in such a way that the documentation is right there in the source code *and* is available at run-time (with the ‘__doc__’ magic attribute). PEP 256 has links to the various specifications that give detailed information on guidelines for writing good docstrings, and for how good docstrings will be used by other tools. > So what's the recommended way of dealing with stuff like this in > larger projects with many developers? Choose community-endorsed standards – the PEPs mentioned above, referenced from PEP 256 – and discuss the benefits of them with your team. -- \ “I think it would be a good idea.” —Mohandas Gandhi (when asked | `\ what he thought of Western civilization) | _o__) | Ben Finney