Doc on |foo| style comments

[Xiaohan Wang (王消寒)]

Happy New Year Chromium Devs!

I have been writing comments like this for years:

// FooClass uses |foo| in FooFunction() blabla.

Recently in a code review, I was asked why we use |...| on variables, and to my surprise I can't find any documentation or style guide to support it. Have I been doing it wrong, or has the documentation been updated so this is no longer recommended/required? Thanks!

Best,

Xiaohan

[Peter Kasting]

It's never been part of the formal style guide, and it's not required.  It's a common practice, and AFAIK the origin is to clarify when something is a variable name vs. a word or something else.  Functions get a trailing () and are thus usually obvious, but variables often aren't.  Consistently using || means there's never ambiguity.

But if people don't want to do it, they aren't required to.

PK

[Peter Boström]

Using |foo| notation gives nice clickable links in code search, so that's nice. See: https://cs.chromium.org/chromium/src/pdf/pdf.h?type=cs&q=//.*%5C%7C&sq=package:chromium&g=0&l=113

--
--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev
---
You received this message because you are subscribed to the Google Groups "Chromium-dev" group.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-dev/CAAHOzFCJracVLoqyxupne9d7VGCYZfphyqp%2BfHXYPJP2mDiszQ%40mail.gmail.com.

[Xiaohan Wang (王消寒)]

Thanks! That all make sense!

Now I wonder how I learned this? Maybe also in code reviews? :)

Does it make sense to document this "common practice" somewhere so that it's easier to point to people when doing code reviews? It doesn't have to be a requirement, but rather an acknowledgement of the existing common practice with some benefits, e.g. readability and codesearch convenience as pointed out above. 

[dan...@chromium.org]

Seems like something nice to add to the Dos and Don'ts page. Thanks.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-dev/CAF1j9YO%2B3m54s7N9b_y%3DeU0%3DHe3U9%2B69Uke5Ax2%3DCd%2BFwpe%2BHg%40mail.gmail.com.

[Xiaohan Wang (王消寒)]

Thanks! CL: https://chromium-review.googlesource.com/c/chromium/src/+/1398369

[Mike Pinkerton]

It was a notation we used at Netscape, and likely propagated to Mozilla. A lot of the early Chromies started there, so that's likely one origin. 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-dev/CAF1j9YO_RLJH3VuQ_4XCMzfs%3DupTHWC0dvB8EZ2daHbXoL1qeA%40mail.gmail.com.

--

Mike Pinkerton
Mac Weenie
pink...@google.com