++yehuda, on preferring to be non-prescriptive; there seem to me to be places where block or single-line c++ comments work better, and it is preferable for the developers maintaining a file to pick from the available options Matt On Mon, Aug 21, 2017 at 7:13 AM, Yehuda Sadeh-Weinraub <ysadehwe@xxxxxxxxxx> wrote: > On Mon, Aug 21, 2017 at 12:49 PM, John Spray <jspray@xxxxxxxxxx> wrote: >> On Fri, Aug 18, 2017 at 10:18 PM, Alfredo Deza <adeza@xxxxxxxxxx> wrote: >>> 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. >> >> I think that's more of a style guide for the documentation .rst source >> code, I was thinking of a style guide for the content itself. >> > > Ceph style guide: > > https://github.com/ceph/ceph/blob/master/CodingStyle > > However, we don't follow it religiously, most don't know it exists I > think. Comments-wise, there's nothing explicit there, and the google > guide that we derive from is pretty lax. I don't think we should force > a specific comments style, it's annoying. > > Yehuda > > >> John >> >>>> >>>> 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 > -- > 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 -- -- Matt Benjamin Red Hat, Inc. 315 West Huron Street, Suite 140A Ann Arbor, Michigan 48103 http://www.redhat.com/en/technologies/storage tel. 734-821-5101 fax. 734-769-8938 cel. 734-216-5309 -- 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
