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. 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. 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. _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
