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

From: Justin M. Lewis (boost_at_[hidden])
Date: 2003-05-03 13:55:34

----- Original Message ----- 
From: "Terje Slettebø" <tslettebo_at_[hidden]>
To: "Boost mailing list" <boost_at_[hidden]>
Sent: Saturday, May 03, 2003 2:25 AM
Subject: Re: [boost] Re: in/out parameters, codingstylesandmaintenance

> >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.

If you start the project and use this convention throughout, then this isn't
a problem.

>
> 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.
>

So what?  Nothing is enforcing what the called code does in ANY of the
conventions suggested, except const meaning that it can't change, but, since
that's not what you're talking about here, that's not an issue.

> 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.

As I've already said, the convention would not have to be used universally
in every library everywhere for it to be useful in a specific project.
Since we all understand the STL, it doesn't need to use this convention, the
point is for it to be used inside a project to make it clear what that code
does.

>
> 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.

And, once again, naming conventions are NOT a solution to this.  You cannot
appropriately name functions in all cases to tell you how they're treating
the params passed.  That's not a realistic expectation, unless you want
function names that are 200 characters long.

>
> 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.
>

Looking a function signature up becomes a nightmare when there are
potentially 100's of them.  So, that's hardly a realistic solution.

> 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.
>

Come on, disrupts reading flow?  The last doesn't disrupt anything, it just
makes it blatantly clear that display is going to change its parameter.

> 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.

Try an actual example?  Any function that takes a large struct as a
parameter to modify.  How about something that's going to modify a string?
Or, maybe you have an output function that outputs a sorted vector, so the
vector is goign to get modified before it's output.  The first example is
the most likely.  Go browse through the Windows API, out and in/out params
happen all over there.  Again, go look through some COM objects, it's
happening all over there.

When you say, let's try an actual example, what do you expect, do you want
me to write a whole program?  I would think that anyone who's been doing
software work, especially anyone who has ever supported old code, would have
seen examples of exactly what I'm talking about.  But, outside of that, I've
given plenty of examples.

And, again, in response to Bo Persson, since this outlook express quirk
won't let me respond to him, or anyone else using the news group rather than
the e-mail list, directly.

"I would never, ever be able to come up with a function like sscanf. This is
C-style experimental overloading; in C++ terms sscanf is sort of overloaded
on the format string.

In C++ we can avoid all this by using stringstream."

That's an absolute avoidance of the question.  You keep claiming good naming
convention is the solution to everything, so give a function LIKE sscanf a
good name.  I understand it's from teh C library, but, the fact of the
matter is, functions like that DO exist in C++ code.

"I wouldn't write a function with a hundred calls either. :-)"

While you might not, and most people wouldn't.  Release the code for 8 years
or so, let several different people work on it, give them all tight
deadlines, and then come back and see how many 10 minute hacks have been
thrown in to add a quick bug fix, or a new feature, or a retrofit, then see
how long your nice short well thoughout functions have become.

The problem here is, in a lot of environments, after a few years code
becomes totally obfuscated.  If you've never had to work in such an
environment, well, then, be happy.  But, for a lot of us, we know starting
off where our code is headed, no matter how nice and clear we made it in the
beginning.  But, still, in 5 years, when I'm no longer the person working on
my current code, it will still be clear, at the point of invocation, which
calls are modifying parameters, and which aren't.

>
>
> Regards,
>
> Terje
>
> _______________________________________________
> Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost
>