Path: csiph.com!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder1.enfer-du-nord.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!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.011 X-Spam-Evidence: '*H*': 0.98; '*S*': 0.00; 'distinct': 0.04; 'git': 0.07; 'prints': 0.07; '25,': 0.12; 'am,': 0.12; 'edits.': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; 'wiki,': 0.16; "\xa0it's": 0.16; 'wrote:': 0.18; 'commit': 0.21; 'received:209.85.210.174': 0.21; 'received:mail- iy0-f174.google.com': 0.21; 'header:In-Reply-To:1': 0.22; '(or': 0.22; 'messages.': 0.25; 'code': 0.26; 'function': 0.27; 'version,': 0.28; 'second': 0.28; 'message-id:@mail.gmail.com': 0.29; 'convention': 0.29; 'print': 0.29; 'definition': 0.30; 'generally': 0.30; 'either.': 0.30; 'exist.': 0.30; 'sun,': 0.30; 'usually': 0.31; 'go.': 0.32; "i've": 0.32; 'anyone': 0.32; 'there': 0.33; 'fault': 0.34; 'to:addr:python-list': 0.35; 'things': 0.35; 'subject:]': 0.36; 'but': 0.37; 'received:google.com': 0.37; 'received:209.85': 0.38; 'uses': 0.38; 'think': 0.38; 'received:209': 0.39; 'to:addr:python.org': 0.40; 'more': 0.61; 'ways,': 0.67; 'funny': 0.76; 'why?': 0.77; '("this': 0.84; 'habit': 0.84 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:content-transfer-encoding; bh=8dyULFc7w6nie5g1GgPOIiCM1Zm5fv+m//gUCBAGux0=; b=rWah920yfpyJw3Id5Uppv7KJpEg7g2qlFG+7GfBxQsnBoldiidDxXiH7RLR5r230m8 7YILcjiI9lzCD5XP3V+QpUoh7K4KHvLyjXXHt0T1KiPnqqNPbWm8tFfMDLLW3QXS7D8H MPNW1NYy3LhCnsT8P5W3/AVHHMP/hfMpYbgFzz0TodmEsV73TvpJT0TecNm+jjDkjbfS ptLp1fFsWYXFkk+/yo8Oiu6KF3aJY6d9XLXrZ+rFG4ydRykK4dhoCGyif4y2rtOEtcU6 xSq3+9X35zr9AfQeZF/SDlQ6iUEnhEHrldxEr0mdBp+sefhuqzLCojvcgAG+ugBrHjJR 7KBQ== MIME-Version: 1.0 In-Reply-To: <718EB1AF094B43D99E697086DE9B5192@gmail.com> References: <4f6e2265$0$1382$4fafbaef@reader2.news.tin.it> <718EB1AF094B43D99E697086DE9B5192@gmail.com> Date: Sun, 25 Mar 2012 09:36:46 +1100 Subject: Re: verbs in comments [OT] From: Chris Angelico To: python-list@python.org Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.12 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: 26 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1332628608 news.xs4all.nl 6940 [2001:888:2000:d::a6]:32974 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:22128 On Sun, Mar 25, 2012 at 7:32 AM, Colton Myers wrot= e: > > // Print the number of words... > // Prints the number of words... > > I've seen it both ways, and I don't think anyone will fault you for eithe= r. > =A0I usually use the first version, "commanding" the code to do what I wa= nt. > =A0It's also a habit because that's the form one uses in git commit messa= ges. It's funny how these things go. There are multiple distinct conventions, and regarding function definition comments (or docstrings), both of those do definitely exist. I think I've seen more code in the second form ("this is what this code does"), but both are prevalent. Regarding git commit messages, the convention generally is to write in the present tense ("this is what this commit does"), but on a wiki, edit summaries are more often in the past tense ("this is what I edited"). Why? Because on a wiki, nobody's going to 'git cherry-pick' the edits. ChrisA