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. 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
