Ned Batchelder had an interesting post a few days ago about why code comments should be written as complete sentences, rather than fragments. The main point is that with an unterminated phrase or sentence fragment it isn't always clear that the thought has been completed (i.e., maybe the full comment isn't even present in the code). Another benefit of writing out the full sentence is it is more likely to be grammatically correct, which may help a developer for whom English is not their primary written language -- a fragment may leave out articles or prepositions that seem implicit, but convey important nuance. I think it's a good point, and intend to pay more attention to how I write comments and docstrings. http://nedbatchelder.com/blog/201401/comments_should_be_sentences.html Doug -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140114/db4fa697/attachment.html>