Path: csiph.com!usenet.pasdenom.info!aioe.org!news.stack.nl!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: UNSURE 0.241 X-Spam-Level: ** X-Spam-Evidence: '*H*': 0.54; '*S*': 0.02; 'def': 0.12; '"""write': 0.16; 'marco': 0.16; 'url:file': 0.16; 'url:py': 0.16; 'wrote:': 0.18; 'module': 0.19; 'code,': 0.22; 'example': 0.22; 'header :User-Agent:1': 0.23; 'regardless': 0.24; 'file.': 0.24; 'header :In-Reply-To:1': 0.27; 'point': 0.28; 'comments': 0.31; 'phone:': 0.31; 'file': 0.32; 'stuff': 0.32; 'quite': 0.32; 'url:python': 0.33; 'but': 0.35; 'received:google.com': 0.35; 'add': 0.35; 'similar': 0.36; 'url:org': 0.36; 'clear': 0.37; 'to:addr:python- list': 0.38; 'to:addr:python.org': 0.39; 'how': 0.40; 'skip:u 10': 0.60; 'is.': 0.60; 'url:3': 0.61; 'making': 0.63; 'charset:windows-1252': 0.65; 'header:Reply-To:1': 0.67; 'line,': 0.68; 'url:4': 0.69; 'reply-to:no real name:2**0': 0.71; 'deserves': 0.84; 'url:cpython': 0.84; 'demand': 0.91; 'houses': 0.91; 'acknowledge': 0.93 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:message-id:date:reply-to:user-agent:mime-version:to:subject :references:in-reply-to:content-type:content-transfer-encoding; bh=AnNYv9SkPuWBG1kYPDZU7AcDk+2BJbsP341qWFQ9Z1w=; b=Sc26AmL+V5oz/g0yBHGlrSmkLUQSGe0jQkMzlvUhSB43DAUh/NmgK3oeW0mURzVdxP /1JE1I8ifYF++mRildgRVQGiwYvqTGQsLt2jloNDnnc6RdW1wpnLuv910q5RhZDjBNBQ Rd0GzCvOb4JoWmo1Ei6A0x+ZtaWvuNPmdEuTQHxHAn2KTiY2rB9WUo6PWBn5BhV+OC3Z WfY1j1339CJ6KB519gw0lLAdgaf9eO3V2GASGtCLjkM85s1glH4NWgbgWOu9A+a9V2X3 HubHfAXAWATDOjf1COfnqt/J3/MVpQ3UAruvXpMJeGyUPgxNjMxxFEeRSaLfnCFU9xbP YX1A== X-Received: by 10.180.11.97 with SMTP id p1mr15248474wib.22.1416919226899; Tue, 25 Nov 2014 04:40:26 -0800 (PST) From: Marco Buttu X-Google-Original-From: Marco Buttu Date: Tue, 25 Nov 2014 13:40:08 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.1.2 MIME-Version: 1.0 To: python-list@python.org Subject: Re: Most gratuitous comments References: <546d7505$0$12899$c3e8da3$5496439d@news.astraweb.com> <25fa214f-2060-46a8-bebf-d191d69e9a9c@googlegroups.com> <546e7644$0$13014$c3e8da3$5496439d@news.astraweb.com> <6ab51e97-19c5-4008-a755-c55eb71469ba@googlegroups.com> <87fvdd6o5c.fsf@elektro.pacujo.net> In-Reply-To: <87fvdd6o5c.fsf@elektro.pacujo.net> Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Mailman-Approved-At: Tue, 25 Nov 2014 13:42:24 +0100 X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: mbuttu@oa-cagliari.inaf.it 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: 29 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1416919345 news.xs4all.nl 2837 [2001:888:2000:d::a6]:56508 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:81506 On 21/11/2014 07:52, Marko Rauhamaa wrote: > sohcahtoa82@gmail.com: > >> >My point was that I was making fun of CS professors that demand a >> >comment on every line of code, regardless of how clear the line of >> >code is. > Unfortunately, a lot of software houses do a similar thing. Not quite > every line, but stuff like: > > def write_line_to_file(file, line): > """Write a line to a file. > > file is the file to add a line to > line is the line to add to the file""" > ... To acknowledge the OP, the statistics module deserves to be taken as example for writing good comments and docstrings: https://hg.python.org/cpython/file/3.4/Lib/statistics.py -- Marco Buttu INAF-Osservatorio Astronomico di Cagliari Via della Scienza n. 5, 09047 Selargius (CA) Phone: 070 711 80 217 Email: mbuttu@oa-cagliari.inaf.it