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
