[openstack-dev] writing comments as complete sentences

Doug Hellmann doug.hellmann at dreamhost.com
Tue Jan 14 13:01:18 UTC 2014

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.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140114/db4fa697/attachment.html>

More information about the OpenStack-dev mailing list