Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.python > #59521
| Path | csiph.com!usenet.pasdenom.info!news.etla.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed4.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail |
|---|---|
| Return-Path | <rosuav@gmail.com> |
| X-Original-To | python-list@python.org |
| Delivered-To | python-list@mail.python.org |
| X-Spam-Status | OK 0.015 |
| X-Spam-Evidence | '*H*': 0.97; '*S*': 0.00; '16,': 0.03; 'parameters': 0.04; 'bits': 0.09; 'worse': 0.09; 'begging': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; "he'd": 0.16; 'programmer,': 0.16; 'subject:program': 0.16; 'subject:skip:u 10': 0.16; 'sat,': 0.16; 'wrote:': 0.18; 'code.': 0.18; 'all,': 0.19; 'documented': 0.24; 'of.': 0.24; 'stick': 0.24; 'least': 0.26; 'certain': 0.27; 'values': 0.27; 'header:In- Reply-To:1': 0.27; 'function': 0.29; 'am,': 0.29; 'strongly': 0.30; 'message-id:@mail.gmail.com': 0.30; 'went': 0.31; 'code': 0.31; 'comments': 0.31; 'agreed.': 0.31; 'description,': 0.31; 'doc': 0.31; 'with,': 0.31; 'figure': 0.32; "i'd": 0.34; 'something': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'false': 0.36; 'useful': 0.36; 'nov': 0.38; 'to:addr:python-list': 0.38; 'to:addr:python.org': 0.39; 'even': 0.60; "you're": 0.61; 'great': 0.65; 'yourself': 0.78; "else's": 0.84; 'subject:else': 0.84; 'luxury': 0.91; 'poorly': 0.93; '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 :content-type; bh=i6MQ7OKKR+2InsRw6/UPW2ZLTF/AFV86tWew4VhfcaU=; b=X6Yvg9Qycdk55Fq0bgIdFlxqWm1+bEAeI8eyedz6BIR6nHTINYkzNi5uF//5JL9UCA O37aMk+ID8ydJ5PxVEY3VN/Hx7Ky/lggpYeMnLfW7aCIAVO+MeN/8fhN0uZfn5nA2bmS 6Ig5k7ccnAMegHJ3BTKqVSYEfsm1CrzHWk4w8jzu1jUGfBPPQTYE7JdWONQIZdcytpS6 eqeSHczNTvnXBYQkAYStDEoX06vsazKvKc0B03gM3N1fl6zjOvY8VTKbb8ACiGxWZgGI 3Ho7DmBrSqMyFEYynEEoQD2Fo+8aSwLFvKagA5wQbkUdwdtJOMYjlP26SxrEIJ0Y7bDN UMug== |
| MIME-Version | 1.0 |
| X-Received | by 10.66.157.165 with SMTP id wn5mr6996536pab.169.1384524183711; Fri, 15 Nov 2013 06:03:03 -0800 (PST) |
| In-Reply-To | <1850721170.38748132.1384523341886.JavaMail.root@sequans.com> |
| References | <19cb1c85-1c01-4c53-a26a-29f96c5926eb@googlegroups.com> <1850721170.38748132.1384523341886.JavaMail.root@sequans.com> |
| Date | Sat, 16 Nov 2013 01:03:03 +1100 |
| Subject | Re: understanding someone else's program |
| From | Chris Angelico <rosuav@gmail.com> |
| To | python-list@python.org |
| Content-Type | text/plain; charset=ISO-8859-1 |
| X-BeenThere | python-list@python.org |
| X-Mailman-Version | 2.1.15 |
| Precedence | list |
| List-Id | General discussion list for the Python programming language <python-list.python.org> |
| List-Unsubscribe | <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe> |
| List-Archive | <http://mail.python.org/pipermail/python-list/> |
| List-Post | <mailto:python-list@python.org> |
| List-Help | <mailto:python-list-request@python.org?subject=help> |
| List-Subscribe | <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe> |
| Newsgroups | comp.lang.python |
| Message-ID | <mailman.2653.1384524194.18130.python-list@python.org> (permalink) |
| Lines | 19 |
| NNTP-Posting-Host | 2001:888:2000:d::a6 |
| X-Trace | 1384524194 news.xs4all.nl 16007 [2001:888:2000:d::a6]:45283 |
| X-Complaints-To | abuse@xs4all.nl |
| Xref | csiph.com comp.lang.python:59521 |
Show key headers only | View raw
On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant <jeanmichel@sequans.com> wrote: > If the documentation is sparse, writing the doc yourself is one way to dive into someone else's code. To begin with, you can stick to the function purpose, and for the WTF functions try to document the parameters and return values as well. Agreed. I just had someone do that with my code - it was sparsely commented, and he went through adding docs based on what he thought functions did (based on their names and a cursory look at their bodies - return values, particularly, were often documented by description, which wasn't particularly useful with certain callbacks). Seeing where he'd misdescribed something was a great way for me to figure out which functions were poorly named, or at least begging for better comments. If you have the luxury of working with the original programmer, that would be something I'd strongly recommend. Even if you can't, try to set some comments down; but be aware that false comments are worse than none at all, so do notate which are your comments and which bits you're particularly unsure of. ChrisA
Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
understanding someone else's program "C. Ng" <ngcbmy@gmail.com> - 2013-11-15 03:05 -0800 Re: understanding someone else's program Ben Finney <ben+python@benfinney.id.au> - 2013-11-15 22:19 +1100 Re: understanding someone else's program Joel Goldstick <joel.goldstick@gmail.com> - 2013-11-15 08:39 -0500 Re: understanding someone else's program William Ray Wing <wrw@mac.com> - 2013-11-15 08:50 -0500 Re: understanding someone else's program Chris Angelico <rosuav@gmail.com> - 2013-11-16 01:03 +1100 Re: understanding someone else's program Denis McMahon <denismfmcmahon@gmail.com> - 2013-11-15 17:41 +0000 Re: understanding someone else's program Laurent Pointal <laurent.pointal@free.fr> - 2013-11-18 23:42 +0100
csiph-web