Reformat the comm-central C++ code base to Google coding style

RESOLVED FIXED in Thunderbird 68.0

Status

enhancement
RESOLVED FIXED
3 months ago
7 days ago

People

(Reporter: jorgk, Assigned: jorgk)

Tracking

Trunk
Thunderbird 68.0

Firefox Tracking Flags

(Not tracked)

Details

Attachments

(2 attachments)

As per:
http://lists.thunderbird.net/pipermail/maildev_lists.thunderbird.net/2019-April/001558.html

M-C have reformatted their entire C++ code base (bug 1188202) and are continuing to do so (bug 1519636). They even reformatted the mozilla-esr60 branch (bug 1513900).

I intend to do the same for the comm-central code base and now is a good time to start to get it all done before the end of the 68 cycle so that future updates to comm-esr68 will be easy.

I will start now with low-traffic directories, like

  • mail/ - Very little C++ code there
  • ldap/
  • db/
  • common/

then slowly moving through mailnews/, again starting with low-traffic directories like db, extensions, import, intl, jsaccount, mapi so that no C++ patches which are in development will be invalidated. I see that the remaining de-RDF patches have little C++ content in them, so even if they don't land within the 68 cycle, it wouldn't be a big problem.

Notes:

  1. mach clang-format -p comm/dir/of/your/choice, issued from the M-C top source directory.
  2. Philipp requested calendar/ excluding libical to be included, so that would be calendar/base/backend/libical and not calendar/libical.
  3. Looks like # ignore-this-changeset needs to be included after the commit message.

mach clang-format -p comm/calendar/base/backend/libical.

I don't know that we want to review these changes, I don't think a human will have a very good time here. But anyway, this is the first patch.

Note some "features" of the style that might not be anything we all like:

+ private:
+  XpcomBase(XpcomBase const&);

+  if (day_of_week < 7) icaltime_adjust(&icalt, 7 - day_of_week, 0, 0, 0);

+  if (paramkind == ICAL_X_PARAMETER) {
+    icalparameter *icalparam =
+        FindParameter(mProperty, param, ICAL_X_PARAMETER);

so private and friends are actually indented by one space only. Simple ifs are one-liners now, and of course the indentation is two spaces generally except for "continuation" lines which are indented by four spaces.

Assignee: nobody → jorgk
Status: NEW → ASSIGNED
Attachment #9060074 - Flags: review?(philipp)
Keywords: leave-open
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/40bbc1563eda
Reformat to Google coding style in mailnews/mapi. rs=reformat
https://hg.mozilla.org/comm-central/rev/babef6da7d89
Reformat to Google coding style in mailnews/intl. rs=reformat
https://hg.mozilla.org/comm-central/rev/ce1d3195faae
Reformat to Google coding style in mailnews/jsaccount. rs=reformat
https://hg.mozilla.org/comm-central/rev/dd001e837a5e
Reformat to Google coding style in mail/. rs=reformat
https://hg.mozilla.org/comm-central/rev/506e8bcb9873
Reformat to Google coding style in common/. rs=reformat
https://hg.mozilla.org/comm-central/rev/0c50a354ca18
Reformat to Google coding style in ldap/. rs=reformat
Comment on attachment 9060074 [details] [diff] [review]
1546364-calendar.patch

Review of attachment 9060074 [details] [diff] [review]:
-----------------------------------------------------------------

Thanks for the patch!
Attachment #9060074 - Flags: review?(philipp) → review+

(Side note: I care less about C++ formatting so I'm going to take what clang-format gives us)

Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/800083958fbf
Reformat to Google coding style in calendar/base/backend/libical. r=philipp
https://hg.mozilla.org/comm-central/rev/4d5ec0d7a32c
Reformat to Google coding style in db/. rs=reformat
https://hg.mozilla.org/comm-central/rev/bca950c87a07
Reformat to Google coding style in mailnews/mime. rs=reformat
https://hg.mozilla.org/comm-central/rev/9d2f71d5e74d
Reformat to Google coding style in mailnews/import. rs=reformat
https://hg.mozilla.org/comm-central/rev/1b6a82d5c491
Reformat to Google coding style in mailnews/extensions. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/d2800cf831c1
Reformat to Google coding style in mailnews/db. rs=reformat
https://hg.mozilla.org/comm-central/rev/33f38e5bef35
Reformat to Google coding style in mailnews/local. rs=reformat
https://hg.mozilla.org/comm-central/rev/2d54904493f8
Reformat to Google coding style in mailnews/build. rs=reformat

OK, unless I missed something, all the first levels are done:
calendar, common, db, ldap, mail. Not doing rdf, which will be removed, and suite.

Of the subdirectories of mailnews, these are done:
build, db, extensions, import, intl, jsaccount, local, mapi, mime.

That leaves: addrbook, base, compose, imap, news. The former two will be next, the latter three have some active patches in bug 1532388 and bug 1538948.
EDIT: base is waiting for bug 697522.

Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/72b0cb7ae598
Reformat to Google coding style in mailnews/addrbook. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/9e527e651e5c
Reformat to Google coding style in mailnews/news. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/ee166a9bb9e0
Reformat to Google coding style in mailnews/base/search. rs=reformat
https://hg.mozilla.org/comm-central/rev/572f63e71e6e
Reformat to Google coding style in mailnews/imap (part 1). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/4983b08e301a
Reformat to Google coding style in mailnews/imap (part 2). rs=reformat DONTBUILD
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/c6597fe7374a
Reformat to Google coding style in mailnews/imap (part 3). rs=reformat

Note that M-C changed the "pointer style" in bug 1547143, that is whether char *x or char* x is used. Before the reformat picked the most prevalent style in the source file, now it always forces the "left style". Since comm-central mostly uses "right style" I intend to finish the reformatting with that style. I have therefore backed out https://hg.mozilla.org/mozilla-central/rev/25e1607e6f1e locally for the rest of the work here since I don't intend to reformat everything again with "left style".

In the future, we either have to reformat to "left style" or negotiate with M-C to include "right style" in their configuration. I asked in bug 1547143 comment #8.

I do think we'd want to go with the m-c style, and I'm glad they made the choice they made. That's the more clear version, since it's saying which type x is quite more clearly than the other style.

M-C picked the prevalent style, see bug 1547143 comment #5, to avoid discussions. The aim was to make it consistent. As far as I can see, everything reformatted in C-C so far established "right style" as the prevalent style.

The comment would have you believe that but I don't see any of that in the code. And there is: https://hg.mozilla.org/mozilla-central/rev/25e1607e6f1e#l1.18 saying left style (e.g. char16_t* string) is what should be used.

Well, be default, clang-reformat reformatted to the prevalent style. After they were done reformatting M-C, someone complained that the result was inconsistent. So Sylvestre investigated what it would take to make it consistent. The answer was that in M-C overall, "left style" it predominant. That is not the case for C-C. Let me finish here, it's about 90% done, and then we see whether we want yet another reformat to switch the stars from right to left.

I think we should avoid the discussion. If you have some spare time, research it. I just spent five minutes reading:
https://stackoverflow.com/questions/2660633/declaring-pointers-asterisk-on-the-left-or-right-of-the-space-between-the-type

Some quotes:
It's a matter of preference, and somewhat of a holy war, just like brace style."
Many opinions, but no "right" way here.

This is interesting:
You might mistakenly declare someType* one, two; thinking that they are both pointers but only the variable one is a pointer; two is just a someType. Declaring as someType *one, *two avoids this problem.

I've done a bit of experimenting. This can also be run as ../mach clang-format -p comm/ or with a comm/subdir. Then comm-central's .clang-format and .clang-format-ignore take effect (although I still have to workout what exactly goes into the latter). The idea is to exclude suite/, rdf/ and libical.

Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/83bbcac4d9a6
Fix white-space/tab issues in mdimporter/main.c. rs=white-space-only
https://hg.mozilla.org/comm-central/rev/96a805927f55
replace tabs with spaces in ldap/ C files and fix comments badly formatted by reformatting. rs=white-space-only
https://hg.mozilla.org/comm-central/rev/dc3b0d8e7139
Repeat running clang-format on ldap/ and mailnews/mime. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/4cf00667dae3
add .clang-format to use derived/prevalent pointer aligment. rs=reformat
https://hg.mozilla.org/comm-central/rev/91500d83151e
Repeat running clang-format on db/. rs=reformat
https://hg.mozilla.org/comm-central/rev/db283bd18902
Fix line length indicator in db/ damaged be reformatting. rs=reformat DONTBUILD
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/979340ae8f89
Reformat to Google coding style in mailnews/compose (part 1). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/6b0afa688835
Fix badly formatted comments in mailnews/mime. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/d9054ea0d4d7
Fix badly formatted comments in mailnews/jsaccount. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/d94dffece975
Fix badly formatted comments in mail/ and mailnews/mapi. rs=reformat
https://hg.mozilla.org/comm-central/rev/28c5478ca164
Fix badly formatted comments in mailnews/local. rs=reformat
https://hg.mozilla.org/comm-central/rev/6bd11ad2949d
Reformat to Google coding style in mailnews/compose (part 2). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/00dbf8bfc8eb
Reformat to Google coding style in mailnews/base/util. rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/41b59070386c
Reformat to Google coding style in mailnews/base/public and mailnews/base/test. rs=reformat

I found another non-libical file that needed reformatting.

Attachment #9064711 - Flags: review?(philipp)

The "*" and the "&" goes with the type, not with the variable.

See Mozilla code style guide https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style
SomeMap::GetValue(const nsString& key, nsString& value);
GetStringValue(nsAWritableCString& aResult)
const nsACstring& aStr,
mozilla::UniquePtr<const char*>&& aBuffer,
void DoSomething(nsIContent* aContent)
char* warning = GetStringValue();
nsISupports* aOptionalThing = nullptr)
Foo** aResult

Please do not change that. The right style is based on a poo C syntax choice and completely unlogical. From what I saw, mozilla-central didn't change that, either, but kept the style I quoted above.

(In reply to Ben Bucksch (:BenB) from comment #28)

The "*" and the "&" goes with the type, not with the variable.
See Mozilla code style guide https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style

That's a discussion we can have later. We're formatting to Google style and that uses the pointer style prevalent in the file, see: https://google.github.io/styleguide/cppguide.html#Pointer_and_Reference_Expressions
"When declaring a pointer variable or argument, you may place the asterisk adjacent to either the type or to the variable name: ... You should do this consistently within a single file, so, when modifying an existing file, use the style in that file."

Mozilla style was abandoned. See:
https://docs.google.com/document/d/1CTaWucldHxEri5BUB1kL4faF4prwPlBa31yHFd-l8uc/edit
"... we will retire the existing Mozilla C/C++ Coding Style"

M-C used the same convention until they decided to go with "left pointer style" about 2/3 though the C-C reformatting effort in bug 1547143. So I will continue with the prevalent style as I started. Then we can decide in another bug whether we want to reformat again and move all the pointers either to the left or to the right. Note that as far as I can see, the M-C decision was based on prevalence, not on personal taste, see bug 1547143 comment #5. If we took the same approach as M-C, we would have to move all the stars to the right since that is prevalent.

Also see:
https://searchfox.org/comm-central/rev/a6f313573be4254edafe723456289680f12b0101/.clang-format#36

OK, moving all the stars to the left changes 515 files and that's a patch of 5.6 MB. Moving them all to the right changes 153 files and is a patch of 1.3 MB. So roughly the ratio in current code is: 1 (left) : 4 (right).

If we use value-free metrics, we should move them all to the right, right?

that uses the pointer style prevalent in the file

Some files in mail use char *foo style, but that's not coherent, it's sometimes this, sometimes that. But it's a violation of the Mozilla Style Guide. These should be fixed to char* foo, not the other way around.

In other words: If you make a change, then it should be in line with the Style Guide, not exactly opposite to it.

Comment on attachment 9064711 [details] [diff] [review]
calendar-base.patch

This should be done by the end of the week.
Attachment #9064711 - Flags: review?(geoff)
Attachment #9064711 - Flags: review?(philipp)
Attachment #9064711 - Flags: review?(geoff)
Attachment #9064711 - Flags: review+
Pushed by geoff@darktrojan.net:
https://hg.mozilla.org/comm-central/rev/e69be81d45d6
Reformat to Google coding style in calendar/base/public. r=darktrojan
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/9ec6e58a9d52
Reformat to Google coding style in mailnews/base/src (part 1). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/8e708fca38cc
Reformat to Google coding style in mailnews/base/src (part 2). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/fa6c146ca1a0
Fix badly formatted comments in mailnews/base/util. rs=reformat
https://hg.mozilla.org/comm-central/rev/019529a494c3
Reformat to Google coding style in mailnews/base/src (part 3). rs=reformat
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/ac04c91f4fff
Reformat to Google coding style in mailnews/base/src (part 4). rs=reformat
Keywords: leave-open

Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/369d4b8f0f0b
Reformat to Google coding style in mailnews/base/src (part 5). rs=reformat

Status: ASSIGNED → RESOLVED
Closed: 2 months ago
Resolution: --- → FIXED

We're done here. I might still revisit some of the earlier landings and tweak some comments. Plus there will be a "report" on the Maildev mailing list.

Target Milestone: --- → Thunderbird 68.0
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/ac121e4bba12
Reformat to Google coding style in mailnews/base/src (part 6). rs=reformat CLOSED TREE
Pushed by mozilla@jorgk.com:
https://hg.mozilla.org/comm-central/rev/2b622f104ac0
Follow-up: Remove incorrect comment. rs=comment-only
You need to log in before you can comment on or make changes to this bug.