Function argument indentation and wrapping

[Brett Wilson]

This has come up twice today, so I added a note to the style guide and
am sending this message.

When writing function declarations and definitions, generally prefer
to have arguments on different lines. Break this when it "makes
sense." Times when it makes sense to break it is when the arguments
have some logical association like "int x, int y" or "char* str, int
str_len" where putting them together on the same line improves
readability. Also you can use one line when everything (including the
function name) fits on one line.

Why? The style guide does this for each of its examples, so I'd
consider this a "soft" rule. I spoke to the former readability team
lead who agreed with this reading. When writing your declaration, try
putting yourself in the shoes of somebody trying to call your
function. Especially if there are many args or very long type names
and templates, it can be difficult to find arguments by scanning
quickly. Separate lines helps this in most cases, but in the case of
"int x, int y" putting them close together on the same line makes it
easier to scan (in my opinion).

So use your judgement, but default to separate lines.

When calling functions you don't have to do one-per-line, but
arguments should generally be aligned. That is, don't have the first
argument on the same line as the function name, then indent the rest
to 4 spaces. Either indent all to 4 spaces, or all to the ( after the
function name.

Related case: member initializers after a class constructor should
follow the same "all or nothing" rule. Have each one on separate lines
with the colon indented to 4 spaces unless everything, including the
class name, fits on one line. Don't split up the indenting like this
Foo::Foo() : first_arg_(0)
second_arg_(0) {
}

Brett

[Mark Mentovai]

Thanks, Brett. I endorse all of these suggestions from a readability
perspective.

Mark

[Peter Kasting]

On Tue, Aug 17, 2010 at 1:57 PM, Brett Wilson <bre...@chromium.org> wrote:

When writing function declarations and definitions, generally prefer
to have arguments on different lines. Break this when it "makes
sense." Times when it makes sense to break it is when the arguments
have some logical association like "int x, int y" or "char* str, int
str_len" where putting them together on the same line improves
readability. Also you can use one line when everything (including the
function name) fits on one line.

For additional clarity, since this is becoming more common in Chrome code, do NOT declare functions like this:

void foo(int arg1, int arg2, int arg3,

    int arg4, int arg5, int arg6);

...unless args 1, 2, 3 are all part of the same "concept" (e.g. a point, or rect, or string), and similarly for args 4, 5, 6.  Unless you have a case like the examples Brett mentions above, you should be doing "all args on one line" or else "one arg per line".  "But my function has 37 arguments" is not a reason to glom random arguments together on the same line. (It's probably a reason to refactor your function so you don't have such a crazy signature.)

PK

[Darin Fisher]

Add to here?  http://dev.chromium.org/developers/coding-style

On Tue, Aug 17, 2010 at 1:57 PM, Brett Wilson <bre...@chromium.org> wrote:

}

Brett

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

[Pam Greene]

On Tue, Aug 17, 2010 at 10:57 PM, Brett Wilson <bre...@chromium.org> wrote:

This has come up twice today, so I added a note to the style guide and
am sending this message.

When writing function declarations and definitions, generally prefer
to have arguments on different lines. Break this when it "makes
sense." Times when it makes sense to break it is when the arguments
have some logical association like "int x, int y" or "char* str, int
str_len" where putting them together on the same line improves
readability. Also you can use one line when everything (including the
function name) fits on one line.

Why? The style guide does this for each of its examples, so I'd
consider this a "soft" rule. I spoke to the former readability team
lead who agreed with this reading.

Actually, the guide at http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Function_Declarations_and_Definitions currently contains

ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
                                             Type par_name3) {
  DoSomething();
  ...
}

Chromium's style guide has nothing specific to say on the question, so we should definitely add our variant to it.

- Pam

When writing your declaration, try
putting yourself in the shoes of somebody trying to call your
function. Especially if there are many args or very long type names
and templates, it can be difficult to find arguments by scanning
quickly. Separate lines helps this in most cases, but in the case of
"int x, int y" putting them close together on the same line makes it
easier to scan (in my opinion).

So use your judgement, but default to separate lines.


When calling functions you don't have to do one-per-line, but
arguments should generally be aligned. That is, don't have the first
argument on the same line as the function name, then indent the rest
to 4 spaces. Either indent all to 4 spaces, or all to the ( after the
function name.

Related case: member initializers after a class constructor should
follow the same "all or nothing" rule. Have each one on separate lines
with the colon indented to 4 spaces unless everything, including the
class name, fits on one line. Don't split up the indenting like this
Foo::Foo() : first_arg_(0)
   second_arg_(0) {
}

Brett

[Peter Kasting]

On Wed, Aug 18, 2010 at 12:05 PM, Pam Greene <p...@chromium.org> wrote:

Actually, the guide at http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Function_Declarations_and_Definitions currently contains

ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
                                             Type par_name3) {
  DoSomething();
  ...
}

Right.  This has always been unclear given the bullet below that example that says "All parameters should be aligned if possible" and thus seems to indicate that this wouldn't normally be preferred style.  I've always treated that example as non-canon (and I think the resulting ruleset is clearer and leads to more readable definitions).

PK