Style guide addition: Use of |pipes| to represent arguments, local and member variables

[Tyler Breisacher]

I've noticed that we use |'s in comments to denote arguments (for
example, |provider_id| in
http://code.google.com/codesearch#OAMlx_jo-ck/src/chrome/browser/ui/webui/options2/content_settings_handler2.h&type=cs&l=103)
and also for member variables (for example, |connection_| in
http://code.google.com/codesearch#OAMlx_jo-ck/src/dbus/bus.h&exact_package=chromium&q=%5C%7C&type=cs&l=132)
but the style guide doesn't officially recommend doing this. I'm going
to add this to http://www.chromium.org/developers/coding-style (for C+
+) and http://www.chromium.org/developers/web-development-style-guide
(for JavaScript). If you have any objections, please let me know.

[Peter Kasting]

Please do not add this.  (I say this as someone who uses these consistently.)

There is nothing wrong with not doing this and no reason to have a style rule about it.

PK

[Dan Beam]

> Please do not add this.  (I say this as someone who uses these
> consistently.)

Hey Peter,

I think Tyler wants to add where |pipe| notation is commonly used
because he and I are unsure of what it means. He had an initial
conception coming on to Chrome relatively recently that it's akin to
using ` on stackoverflow or github or anywhere you'd want text wrapped
with a <code> or <pre> tag in general (if showing documentation in
HTML, that is).

> There is nothing wrong with not doing this and no reason to have a style
> rule about it.

The problem is not with people "not doing this", but with authors
doing this _too_ much and adding |pipes| around anything that should
be monospaced or look like code.

Additionally, we already do this in the style guide around |params|,
but we don't really clarify if that's the only place one should be
doing this (or where else it'd be appropriate).

Please advise,

Dan Beam
db...@chromium.org

[Peter Kasting]

On Wed, Mar 21, 2012 at 4:35 PM, Dan Beam <db...@google.com> wrote:

I think Tyler wants to add where |pipe| notation is commonly used

because he and I are unsure of what it means. He had an initial
conception coming on to Chrome relatively recently that it's akin to
using ` on stackoverflow or github or anywhere you'd want text wrapped
with a <code> or <pre> tag in general (if showing documentation in
HTML, that is).

I see.  I'm not opposed to explaining this somewhere, but I don't think the style guide is the right place.  Not only is it optional, it has no real defined meaning.  There's nothing inherently wrong about using it around any piece of text you want.  I think I was one of the first people to use it commonly, and at the time it was just to add clarity when using a variable name in a sentence could be ambiguous.  While some people (including me) now use it more frequently, it's by no means universal on the team and I've seen it used more for the purposes you describe as well.  Given this state, I don't think a style rule is appropriate.

I'm not sure where a better place for this might be.

PK

[David Holloway]

This rule is present in the Objective-C style guide.  It should be in the Chromium style guide too.  It's a good rule and ends debates on comment style.

  http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml?showone=Implementation_Comments#Implementation_Comments

--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev

[Peter Kasting]

On Thu, Mar 22, 2012 at 9:46 AM, David Holloway <dhol...@google.com> wrote:

This rule is present in the Objective-C style guide.  It should be in the Chromium style guide too.  It's a good rule and ends debates on comment style.

If the C++ style guide doesn't have it, one wonders why they elected not to copy the ObjC guide.

I have not seen any debates on codereviews or whatever on comment style.  I continue to feel we would be better without adding this rule.  And since I am usually eager to add new style rules for everything, and am one of the people who use this style most commonly and consistently, I think that says something.

PK

[Rachel Blum]

If the C++ style guide doesn't have it, one wonders why they elected not to copy the ObjC guide.

It got added to the ObjC guide later? (Just a guess...)

I'd prefer to be consistent between ObjC and C++, simply because it's annoying to have inconsistent rules. (Although that's probably just wishful thinking - ObjC will always be somewhat different)

I have not seen any debates on codereviews or whatever on comment style.

As an anecdotal data point, I've seen nits based on pipes, and I've written nits based on pipes. I'm fine with ignoring them, though.

 

 I continue to feel we would be better without adding this rule.  And since I am usually eager to add new style rules for everything, and am one of the people who use this style most commonly and consistently, I think that says something.

Agreed. +1 if we can get it killed in the ObjC style guides. 

Rachel