[openstack-dev] writing comments as complete sentences
cbkyeoh at gmail.com
Wed Jan 22 05:03:19 UTC 2014
On Thu, Jan 16, 2014 at 5:35 AM, Renat Akhmerov <rakhmerov at mirantis.com>wrote:
> I absolutely agree with that. Honestly, I don’t even understand why it can
> be different (not compliant with regular grammar rules). Comments are
> supposed to clarify things so they should be worded very clearly and read
> as normal English sentences. Additionally it’s one of the small bricks that
> the entire coding culture is built of.
I agree, but I think its important when giving review feedback to not just
say "please fix up the grammar here" or "this bit doesn't make sense" but
instead provide a complete suggestion of how it should be written as the
author may not be a native english speaker.
> Renat Akhmerov
> @ Mirantis Inc.
> On 14 Jan 2014, at 06:00, Jay Pipes <jaypipes at gmail.com> wrote:
> > On Tue, 2014-01-14 at 08:01 -0500, Doug Hellmann wrote:
> >> 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).
> > # Supported.
> > -jay
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev