On Fri, Aug 18, 2017 at 7:35 AM, John Spray <jspray@xxxxxxxxxx> wrote: > On Thu, Aug 17, 2017 at 6:25 PM, Gregory Farnum <gfarnum@xxxxxxxxxx> wrote: >> On Thu, Aug 17, 2017 at 4:22 AM, kefu chai <tchaikov@xxxxxxxxx> wrote: >>> hi Amit, >>> >>> i found that you started to encourage developers to use "/* */" for >>> multiple-lined comment while reviewing pull requests. IIUC, it's more >>> of a gray area, and sort of a personal preferences. so i don't >>> understand why we need to go this way. and i believe, in modern C++ >>> practice, "//" is more common[0], and works better for developers. in >>> the sense that, it's more readable, conforms to C++ standards, and >>> works just fine with editors/tools. >>> >> >> Similarly, do we have a rule or guidance about contractions anywhere? >> >> I can see how that might be desirable for non-native english speakers, >> but it's not a rule of any kind that I'm aware of. Do we want it to >> be? (...perhaps I should add the ceph-china list to this CC). > > Based on the discussion on https://github.com/ceph/ceph/pull/16705, > there doesn't seem to be much support for removing contractions. > > I sympathise with John W's original intent on that PR to make it > easier to sync up upstream docs with commercial products that might > have an IBM-ish style, but I don't think it makes sense to make the > change without making it a rule, and I think it's not something that's > desirable as a rule. > > I would welcome a style guide for our upstream docs though, so that we > could have a place to refer to for any rules we do want to have. We do have a documentation style guide: https://github.com/ceph/ceph/blob/master/doc/start/documenting-ceph.rst#documentation-style-guide Most of the suggestions/rules there aren't really followed :( Hopefully with the new fixes that went in, that will change and prevent us from going astray again. > > John > > 1. As I write that, I realise it's weird that in English we sometimes > use in- to mean opposite and sometimes not! What a language... > > >> -Greg >> -- >> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in >> the body of a message to majordomo@xxxxxxxxxxxxxxx >> More majordomo info at http://vger.kernel.org/majordomo-info.html > -- > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe ceph-devel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
