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

From: Justin M. Lewis (boost_at_[hidden])
Date: 2003-05-03 15:44:05

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

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

How many times do I have to respond to this same point?  Everyone knows how
the STL works, it doesn't need wrapped.  3rd party libraries do NOT make up
the majority of a project, and are generally well understood by everyone
involved, so they wouldn't need to adhere to any conventions either for my
idea to be effectively implemented.

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

If you think it is, then you've never been in the situation where you have
1000's of undocumented functions, and you've never had to trace through a
function where 10's if not 100's of unfamiliar calls are made.  And, if you
think it is a realistic solution, then you're really not seeing the problem
these classes were meant to address.

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

The point here was, if you want examples of people using out and in/out
parameters, there you go, lots of examples.  If you want examples of people
using my idea, well, you're out of luck, because they obviously don't exist,
except in my own code at work, which I'm obviously not allowed to just give
out.

> > 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've given a LOT of function signatures as examples.

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

Again, old code doesn't need changed, because we all ARE familiar with
sscanf, but, you wanted examples of people using out or in/out params, and
there you go, there's an example.  And I said, pretend it's NOT a part of
the standard C library, pretend it's not a call that everyone is familiar
with, try to give it a name such that it explains how all of the params are
used.  It's my example of why naming convention isn't a reasonable solution.

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

Of course they'll be used, if they're already a part of the code, people
aren't going to go strip them out.  Modifying code in a large project is a
PITA.  Besides, no one is going to go modify code they didn't write just to
save them from having to type 5-8 extra bytes.  But, if your argument is
people are going to go out of their way to destroy clear coding styles,
then, again, all of the solutions anyone else has proposed are at least as
likely to be thrown out.

And, again, I HAVE been using these classes.  That's why I brought them
here.  I had a problem with functions not being clear, I found a solution,
that's enforceable, in that people using the libraries I write have to
adhere to it, I know other people like the idea after having discussions
with them, so I thought I'd see about giving it to boost and having it out
there where it's easily accessible to a large number of people.

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