[jira] [Comment Edited] (MESOS-2618) Update C++ style guide on function definition / invocation formatting.

["Michael Park (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MESOS-2618?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14596770#comment-14596770 ] 

Michael Park edited comment on MESOS-2618 at 6/22/15 10:28 PM:
---------------------------------------------------------------

I recently did a little formatting cleanup and received some feedback that relates to this ticket.

In [r35635|https://reviews.apache.org/r/35635], it was noted that we prefer:

{code}
(1)
  delay(flags.executor_shutdown_grace_period,
        self(),
        &Slave::shutdownExecutorTimeout,
        framework->id(),
        executor->id,
        executor->containerId);
{code}

over

{code}
(2)
  delay(
      flags.executor_shutdown_grace_period,
      self(),
      &Slave::shutdownExecutorTimeout,
      framework->id(),
      executor->id,
      executor->containerId);
{code}

We also prefer:

{code}
(3)
  containerizer->wait(containerId)
    .onAny(defer(self(),
                 &Self::executorTerminated,
                 frameworkId,
                 executorId,
                 lambda::_1));
{code}

over

{code}
(4)
  containerizer->wait(containerId)
    .onAny(defer(
        self(),
        &Self::executorTerminated,
        frameworkId,
        executorId,
        lambda::_1));
{code}

Both of the preferred styles above are what {{clang-format}} produces. I think this goes to show that what {{clang-format}} produces is good in most cases (Of course there are short-comings since it's a developing project, but I think the spectacularly bad ones are the ones we should be talking about. Rather than cases like this where either style is just as readable). For example, reasoning through and outlining the exact rules as to why we prefer (3) over (4) is non-trivial nor all that helpful. {{clang-format}} uses penalties for various undesired formatting styles and chooses a style which minimizes the total penalty (as per LaTeX). I think relying on that system would be more systematic and beneficial in terms of time-saving for all of us.


was (Author: mcypark):
I recently did a little formatting cleanup and received some feedback that relates to this ticket.

In [r35635|https://reviews.apache.org/r/35635], it was noted that we prefer:

{code}
(1)
  delay(flags.executor_shutdown_grace_period,
        self(),
        &Slave::shutdownExecutorTimeout,
        framework->id(),
        executor->id,
        executor->containerId);
{code}

over

{code}
(2)
  delay(
      flags.executor_shutdown_grace_period,
      self(),
      &Slave::shutdownExecutorTimeout,
      framework->id(),
      executor->id,
      executor->containerId);
{code}

We also prefer:

{code}
(3)
  containerizer->wait(containerId)
    .onAny(defer(self(),
                 &Self::executorTerminated,
                 frameworkId,
                 executorId,
                 lambda::_1));
{code}

over

{code}
(4)
  containerizer->wait(containerId)
    .onAny(defer(
        self(),
        &Self::executorTerminated,
        frameworkId,
        executorId,
        lambda::_1));
{code}

Both of the preferred styles above are what {{clang-format}} produces. I think this goes to show that what {{clang-format}} produces is good in most cases (Of course there are short-comings since it's a developing project, but I think the spectacularly bad ones are the ones we should be talking about. Rather than cases like this where either way it's just as readable). For example, reasoning through and outlining the exact rules as to why we prefer (3) over (4) is non-trivial nor all that helpful. {{clang-format}} uses penalties for various undesired formatting styles and chooses a style which minimizes the total penalty (as per LaTeX). I think relying on that system would be more systematic and beneficial in terms of time-saving for all of us.

> Update C++ style guide on function definition / invocation formatting. 
> -----------------------------------------------------------------------
>
>                 Key: MESOS-2618
>                 URL: https://issues.apache.org/jira/browse/MESOS-2618
>             Project: Mesos
>          Issue Type: Documentation
>            Reporter: Till Toenshoff
>            Priority: Minor
>
> Our style guide currently suggests two options for cases of function definitions / invocations that do not fit into a single line even when breaking after the opening argument bracket;
> Fixed leading indention (4 spaces);
> {noformat}
> // 4: OK.  
> allocator->resourcesRecovered(  
>     frameworkId,  
>     slaveId,  
>     resources,  
>     filters);
> {noformat}
> Variable leading indention;
> {noformat}
> // 3: In this case, 3 is OK.  
> foobar(someArgument,  
>        someOtherArgument,  
>        theLastArgument);
> {noformat}
> There is a counter-case mentioned as for the latter; 
> {noformat}
> // 3: Don't use in this case due to "jaggedness".
> allocator->resourcesRecovered(frameworkId,  
>                               slaveId,  
>                               resources,  
>                               filters);
> {noformat}
> The problem here seems to be that the counter-case might not be well defined  on when it applies.
> We might want to consider...
> A. removing the variable leading option entirely
> B. define the exact limits on when "jaggedness" applies



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)