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

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

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

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

Please read the premises above. The premise was if you come across a
function you don't know. _Your_ premise for your proposal was the same - if
you come across a function you don't know - at least you don't know what
parameters it takes (and hence if it may modify them). I can't see how using
the convention throughout a project would matter in that case, unless you
use no code except the project code. Does this mean you'd wrap all of the
standard library, too, if you use it, to use this convention?

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

I just enumerated cases where it may or may not be helpful. I think there's
no disagreement on this case.

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

I think it is.

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

I was talking about _new_ code. You said yourself that you don't need to
modify old code for the convention. That leaves new code. The Windows API,
etc. doesn't count in this respect. I meant an example of a function you
might use in a project - preferably a concrete function signature. Then
we'll see if it may be refactored to have a clear meaning, without requiring
this convention.

> When you say, let's try an actual example, what do you expect, do you want
> me to write a whole program?

No, just a single function signature, which you think may need out() or
in_out(), and the semantics of the function. Anyway, you give an example of
sscanf, below here.

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

Yes, I've seen that, but you've already, yourself, stated that old code
didn't need to be changed.

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

sscanf is a quite well-known function, as it exists in the C and C++
standard library. It may easily be looked up in a reference to the library.
Also, it takes pointer parameters - the pointers to the variables it reads
to, so the use of pointer to non-const parameters should be a sign it may
change them. For example:

int *a_ptr; // Note name

// ...

sscanf("...", "...", a_ptr);

Clearly, a pointer is passed to it. Why? Let's look at the variable
declaration of a_ptr. Hm, pointer to non-const, sscanf may well change the
pointee.

All this without looking at the signature to sscanf.

The same goes for explicitly taking the address:

sscanf("...", "...", &a);

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

In such an environment, your in_out() and out() parameters may be the first
to go, as people won't bother to use them, and change the signature to not
use them (or provide an implicit conversion to them.

Anyway, if you think it's a good idea, why don't you try it out? Letting the
rubber meet the road may be way more productive, than trying to convince
people, without existing practice to refer to.

Regards,

Terje