Re: [boost] in/out parameters, coding styles and maintenance[was:class proposal]

From: David Abrahams (dave_at_[hidden])
Date: 2003-04-26 19:14:45

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

> I don't think it's reasonable to compare how things are done in the standard
> library to how things are done in actual code.  

I didn't make that comparison.  Most of my code is not in the standard
library.

> The standard library is STANDARD, we all KNOW what it does, and how
> it behaves, and it's documented all over the place.
>
> My code on the other hand, it's not standard, you have no way of
> knowing how anything I wrote works, without learning the entire
> source.  

In my experience, having to read the entire source base in order to
understand a small piece of it is usually a mark of bad design and
poor documentation.

> And, when we're talking about projects that are potentially millions
> of lines of code, that's not governed by any standard, the problem
> of figuring out what's going on becomes a real issue.  So, I'm not
> advocating, or even suggesting, that the these classes be applied to
> things like the standard library.  I think they would be a useful
> tool for any large project that will be maintained for years on end.

OK.

> Again, try to imagine the situation where you're browsing through source
> files that are 10's of thousands of lines long EACH, looking at 100's of
> unfamiliar function calls, trying to trace how some particular module works.
> You have the option of looking up every function that's called, then every
> function every one of those functions call to see what is ultimately
> happening to the parameters, or, in an environment like I'm suggesting, it
> would be obvious at the invocation point what is happening to the
> parameters.

Yes, it sounds like it could be an advantage in a messy codebase.

>> I prefer some degree of abstraction and information hiding.
>
> Could you explain that to me.  Information hiding?  I'm not terribly fond of
> functions that attempt to hide their purpose from me, that doesn't even make
> sense.  And, some degree of abstraction?  What is it you want to abstract?

You asked, 

    "Would you prefer to have to have a complet understanding of every
     single function call made in a program or would you prefer that
     as much information as possible is given at the point of
     invocation?"

Well, I don't want a *complete* understanding at the level of detail
you imply.  I don't want to know about the internals of every function
call I make.  I don't want to see the types of objects in their
variable names (a la hungarian notation).  I want to deal with
interfaces at a level which is relevant to me as the reader.  I agree
with you that which parameters may be modified is often relevant,
though.

>> 1. I think liberal use of out parameters is bad practice, and I have
>>    no interest in a library which makes bad practice more palatable.
>>    But if you're bound and determined to do it, by all means clarify
>>    by whatever means neccessary.
>
> I don't think I've ever suggested that out parameters should be the NORM.
> I've said that they are practical at some points.  And, I still can't see
> how making it explicit is a bad thing.  

It may even be a good thing if it adds clarity.  I was just explaining
why I'm not enthusiastic about the idea.

> I can't even see how out parameters are bad practice, that seems
> like a bit of an over generalization.  

I didn't say that they are.  Note the words "...liberal use of..."

> In some of the simple examples I give here they'd be bad practice,
> but, in real code, there are places it makes sense to use out
> params.  

Yes.

> out and in_out params are used all over the standard libraries.
> They're used all over the Windows API.  And they're obviously used
> in things like COM and CORBA.  

But you're not going to change those interfaces to use your library
are you?

> And, in other projects I've worked on, they're not the norm, but
> they're not that uncommon.  Jumping through hoops, and taking
> potentially large performance hits to avoid their use seems
> ridiculous to me.

I never said I was jumping through hoops or taking large performance
hits.  When I'm done avoiding out parameters (unless idiomatic), I end
up with a clean interface that's hard to misuse.  As a library
writer that's important to me.

> And, again, while you personally may not like their use, they ARE
> used.

As you've said many times.

> And the whole point of this is to make their use explicit and clear,
> so when someone like you comes along the outcome of the function is
> clear to YOU, the person coming in to maintain the code.  Not to ME
> the person writing the code.

Thanks for looking out for my interests ;-)

I don't have much experience encountering codebases where I'm confused
about which parameters are being modified, where explicit marking
would help much.  Maybe that's why I'm still lukewarm to the idea, but
you don't have to convince me; there are lots of other people on this
list.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com