Re: [boost] Re: in/out parameters, codingstylesandmaintenance

From: Terje Slettebø (tslettebo_at_[hidden])
Date: 2003-05-03 04:25:02

>From: "Justin M. Lewis" <boost_at_[hidden]>

> And, I responded to that claim.  It does what I say it will do, IF you
> choose to use it throughout a project.  IF you pick it up and start using
> it, it will do what I said it will do.  Your claim is only valid in the
case
> where all you work on is old code, and you never do anything new.  I
> responded to the case where it's not used in 3rd party libraries as well.
> So, if your ONLY claim is that it would have to be universally applied by
a
> development team across a project within your own in house code, and
that's
> the part that's impossible to enforce, well, then, so are good naming
> conventions, or any other coding practice.
>
> So, once again, these objects serve their purpose perfectly, as long as
> they're consistently applied across a project, which isn't that hard to
> imagine, or accomplish, or enforce.

Just to try to sum it up a little.

You said at the beginning that with this convention, when you saw a function
you didn't know, you could see it from the function call what may or may not
be changed. We may have to use more nuances, here, as others have pointed
out, as well.

Let's say that you use the convention in the code made in your project, but
the standard library, third party libraries, perhaps other parts of the
company, etc. doesn't use it.

There are several possible cases:

1. You know nothing about the function; you don't know whether it's part of
the group of functions using the convention (such as your project), or not.
In that case, a call like:

f(a);

will tell you nothing. The convention won't help you, in this case.

2. You know that the function is part of the group using the convention
(perhaps by using a special namespace for it), but you otherwise don't know
what it does. In this case, f(a) should then mean that you know it won't
change "a", or it should have said f(out(a)) or f(in_out(a)). This is
provided the function properly use the convention, and doesn't modify "a".
This is a convention, so the code doesn't enforce this. Only the calling
code is enforced, not the called code implementation.

3. You know the function well enough (or you've looked it up) to know what
it does, and you know whether or not it modifies "a". In this case, the
convention is not needed.

4. The code uses appropriate naming, etc., so it should be reasonably clear
in many cases whether or not an argument is being modified. For the cases
where it may not be clear, one may look it up. Also in this case, the
convention is not needed.

Note that in the scenarios that have been presented for this convention, in
this thread, relies on that the only thing you need to know, is whether or
not a function changes its arguments, not what it does. When you read code
to understand it, you may try to follow what it does, not just whether or
not something is changed.

The case where this convention may help is case 2. For case 1, 3 and 4, it
doesn't help. Note that if you mark each function using the convention in
some way, such as putting it in a special namespace, it may help for case 1,
as well.

What some people are saying, is that 3 and 4 may be quite common scenarios,
and as you can always look a function signature up (or use an editor with
this capability), it encompasses case 1 and 2, as well, so it may not be
worth it to add this extra indirection at the call sites. Especially for
idiomatic functions (like stream operators), where what it does is
well-known.

Readability is obviously subjective, but with Bo Persson's posting, it
occurred to me what it is that I had reacted to with this proposal, but
couldn't quite put my finger on it before then: It disrupts the reading
flow.

Consider his examples:

display(name);

display(&name);

display(out(name));

The first may be read as "display name". Clear and simple. If you read the
latter, it becomes something like "display out name"? It's similar with the
second example.

"display" may not be a typical function to modify its argument, so what we
might need is more examples of functions taking in/out or out parameters.
Perhaps you could provide some motivating examples?

You said this could be applied to new code, as well (especially as you may
not want to retrofit this to all existing code), but several pointed out
that in new code, it may be possible to do it so that if in_out or out
parameters are used, you may design the function in such a way that it's
clear what it does. So let's try an actual example.

Regards,

Terje