Re: [lmi] omitting parameter name

[Greg Chicares]

On 2007-4-12 22:36 UTC, Evgeniy Tarassov wrote:
> 
> Greg -- could you please shortly explain what is the LMI guideline for
> omitting/specifying function parameter name?

In my copious free time, I'm updating the style guidelines that
I haven't yet formally published. I propose the addition below [1],
and invite comments; I think it agrees with all your inferences.

> AFAIK a parameter name could be (should be?) omitted if (if and only
> if?) the function parameter meaning could be easily understood from
> its type, like in:

I'd say "should be" and "if and only if".

> class printable
> {
>  void print_me(std::ostream&) const;
> };

I think naming the parameter would make that declaration less good.
What could we name it? Its meaning is just "that ostream we're using".
Its type is its entire meaning. Giving it a name would make the
declaration longer, but not clearer.

> What about mixing styles inside the same function? I.e. omitting one
> parameter name and keeping another one:
> 
> class printable
> {
>  ...
>  void print_me(std::ostream&, bool include_title) const;
> };

Yes, I think it's good to give the obvious parameter no name,
and to give the non-obvious parameter a meaningful name. These
alternatives would be less good IMO:

  void print_me(std::ostream& os, bool include_title) const;
                             ^^^ not helpful

To parse that mentally, I have to waste time reading 'os',
recognizing that it is only a meaningless placeholder, and then
disregarding it. It's easier to parse without that name, because
the name 'os' adds nothing to the meaning. The entire meaning is
given by the type.

That might not save much mental parsing effort, but the cumulative
savings across many declarations can make it significantly easier
to see an entire class declaration's meaning at a glance.

  void print_me(std::ostream&, bool) const;
                               ^^^^ unknown meaning

To parse that mentally, I have to pause at 'bool' and wonder what
it might mean. I have to look for a comment somewhere that might
explain it. If I see this in a header, then the comment might be
on the line above, or somewhere earlier in the header, or even
in a different file that defines the function. It's much easier
to parse with a name like 'include_title', which is required to
indicate its meaning.

---------

[1] Proposed guideline:

<p>
2.15 Don't name a formal parameter [1.3.9] in a function declaration
when its meaning is obvious from its type:
</p>

<pre>
  [members of class X]
  void print(std::ostream&, int number_of_pages);      // Good declaration.
  void print(std::ostream& os, int number_of_pages);   // Less good.
  ...
  void X::print(std::ostream& os, int number_of_pages) // Good definition.
</pre>

<p>
Clearly this function writes the given number of pages of an
<tt>X</tt> object to the given stream. The first parameter needs no
name, because its type imparts its entire meaning. A name like
<tt>os</tt> might change under subsequent maintenance, potentially
creating confusion unless extra effort is spent to change it
identically in both the declaration and the definition; that's too
much work for a name that's nothing but an empty placeholder.
</p>

<p>
The second parameter, however, does need a name, without which it
might be taken as an integer to be inserted into the stream. Express
the meaning in the name, instead of inventing a "dummy" parameter name
that requires a disambiguating comment:
</p>

<pre>
  // 'n' means number of pages.
  void print(std::ostream&, int n); // Poor declaration.
</pre>

<p>
The definition needs a name for any actual argument [1.3.1] that it
uses. The name's length should vary inversely with the obviousness of
the argument's meaning: <tt>standard_output_stream</tt> would be a
poor choice in the example above.
</p>