Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!news.glorb.com!solaris.cc.vt.edu!news.vt.edu!newsfeed-00.mathworks.com!panix!roy From: Roy Smith Newsgroups: comp.lang.python Subject: Re: verbs in comments [OT] Date: Sat, 24 Mar 2012 19:27:12 -0400 Organization: PANIX Public Access Internet and UNIX, NYC Lines: 19 Message-ID: References: <4f6e2265$0$1382$4fafbaef@reader2.news.tin.it> <718EB1AF094B43D99E697086DE9B5192@gmail.com> NNTP-Posting-Host: localhost X-Trace: reader1.panix.com 1332631632 5873 127.0.0.1 (24 Mar 2012 23:27:12 GMT) X-Complaints-To: abuse@panix.com NNTP-Posting-Date: Sat, 24 Mar 2012 23:27:12 +0000 (UTC) User-Agent: MT-NewsWatcher/3.5.3b3 (Intel Mac OS X) Xref: csiph.com comp.lang.python:22129 In article , Chris Angelico wrote: > 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. My recommendation is that for a large project, pick a style and stick with it. There's a couple of reasons for this. One is that it makes it easier to read, but I think the bigger reason is that it makes it easier to write. The best documentation is documentation that gets written. Developers are often poor documenters. If you can give them a structured template, it makes it more likely that they will write something. The more open ended you make it, the more likely it is they'll just get writer's block and end up writing nothing.