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: 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 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: 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 On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant 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