On Tue, Jul 23, 2019 at 2:50 PM Bryce Seager van Dyk <bvan...@mozilla.com> wrote:
> On Sunday, July 21, 2019 at 10:18:02 PM UTC-7, Karl Tomlinson wrote: > > Near the top of > > > https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style > > there is > > > New code should try to conform to these standards, so it is as > > > easy to maintain as existing code. [...] > > > > > > This article is particularly for those new to the Mozilla > > > codebase [...]" Before requesting a review, please read over > > > this document, making sure that your code conforms to > > > recommendations." > > > > > > Firefox code base uses the Google Coding style for C++ code [2] > > > > On reading over the document, the reader finds a number of > > additional guidelines, some of which are complementary or > > orthogonal to Google style and some of which are contradictory. > > > > Can we clarify which documents have precedence so that we can > > spell this out clearly on this page, please? > > > > "we would like to convert entirely to this [Google C++] coding > > style -- perhaps with some exceptions for Mozilla-specific > > constraints". [1] > > Would the Mozilla coding style be the appropriate place to list > > such exceptions? > > The existing recording of a recent resolution [3] on this page > > seems helpful to me. > > > > The reason to think this page might not be the appropriate place > > is because [1] > > > we will retire the Mozilla C/C++ coding style. The intention > > > behind retiring the current Mozilla style is to just stop > > > maintaining it as an active coding style going forward, but the > > > documentation for this coding style will be kept intact. > > > > What is the motivation for keeping intact the legacy coding style? > > Is it to guide those contributing in code that has not yet moved > > to Google style? I wonder how useful that would be given "we now > > have significant inconsistencies in the style of our codebase" > > [1]? > > > > If it is useful to keep intact the documentation of legacy style, > > can we distinguish which are the guidelines that should apply only > > to older code? > > > > "we are not aiming to enforce any naming conventions at this time" > > [1] but both the Google and Mozilla style guides have > > (conflicting) naming conventions. Can we clarify which, if any, > > naming guidelines apply to new and older code? > > > > The other piece of the equation here is [1] > > > our precise coding style will be the result of formatting our > > > tree with clang-format, so by definition our code, when > > > formatted with clang-format, will be following our new coding > > > style. > > > > clang-format doesn't provide compliance with all guidelines in the > > Google style, but it does have precedence, because the only option > > to override is `// clang-format off`. clang-format has its own > > preferences for formatting, many of which are not documented in > > the Google style guide. > > > > Would it be appropriate for the Mozilla coding style page to > > indicate that `./mach clang-format` defines the formatting of C++ > > code and the Google style guide provides other guidelines, which > > should be followed in new code unless there is an exception > > listed? > > > > > https://developer.mozilla.org/en-US/docs/Mozilla/Using_CXX_in_Mozilla_code > > is another page with more guidelines. I assume we would expect > > these to be consistent with those on the Mozilla coding style > > page. I assume "Using C++ in Mozilla code" would take precedence > > over Google style? > > > > [1] > > > https://groups.google.com/forum/#!msg/mozilla.dev.platform/VCLB1Lz4yXc/dNoNVzmlCQAJ > > [2] > > https://google.github.io/styleguide/cppguide.html > > [3] > > https://groups.google.com/forum/#!topic/mozilla.dev.platform/0NFBXe6VnfM > > My opinions (C++ specific) having revised a small amount of the style > guide recently: the less documents that need to be consulted, the better. > Non exhaustive reasons I'd prefer we keep docs lean: > - People may not be aware of a doc. > - It can be hard to determine which docs take precedence. Need docs for > our docs. > - Minimize places to bitrot. > > Following on, I would like our style page ([1] above) to, ideally, offer > clarifications and, rarely and in clearly stated cases, supersede the > Google style. I wouldn't mind if other pages with C++ style rules where > trimmed and merged into this one. I think the guide needs some more work to > get to this point because: > - Old historical content that can now be cut or revised has not yet been. > - C++ style is sprinkled throughout the guide, not just in an isolated C++ > section. > - There are general styling rules that apply to C++ and other areas that > are hard to revise. > - C++ style is also splintered across other pages. > A lot (most?) of the cruft you mention above is just remnants of the old coding style... > Does `./mach clang-format` ever perform formatting inconsistent with > Google style? If so, does it do so in a lot of cases? If not, I like the > idea of our style guide indicating that Google style should be used, unless > where noted in our guide, and having our guide specify those cases, along > with any exceptions where manual styling is required. > FWIW, if ./mach clang-format ever performs formatting inconsistent with the Google style, the correct forum for reporting and discussing that is *not* Mozilla, but rather the LLVM project < https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Formatter>. We're explicitly not trying to maintain either the Google C++ Style or clang-format downstream. :-) > I think the current style docs will continue to be referenced and updated > for the near future. Depending on the motivation for and desire to have a > historical record, perhaps creating a separate location for one would be > worthwhile. > Yep, that makes perfect sense to me. -- Ehsan _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
