The Old Joel on Software Forum: Part 4 (of 5)

Naming args in headers

Disclaimer: this topic is about a trivial detail of C/C++ coding. Read on at your own risk.

Let's imagine you are writing a class in C++. So you have your .h file, where you define your class, and your .cpp file (yes, I'm assuming a standard VS6.0 project here) where you define your implementation. Do you name the arguments to your methods in the class definition? To me this always seemed redundant, but I tend to do it anyway, for clarity I guess. I mean, the whole idea of having to type the method signatures twice is a bit redundant in itself.

I guess if I were writing a true library where I'm only distributing the binaries (something I've never actually had to do), I'd need to provide a complete specification in the header file.

Definitely one of the nice things about Java is it avoids this type of pain.

Still, could one justify only naming the args in the method definition?

Ken
Thursday, February 19, 2004

No justification as such.

I prefer to follow the same approach, i.e. to name the arguments in the class definition itself. Main purpose is that when I need to call the function, I can get to know at a glance the purpose of the arguments ( I've got a weak memory ;) ).

*To me this always seemed redundant, but I tend to do it anyway, for clarity I guess. I mean, the whole idea of having to type the method signatures twice is a bit redundant in itself.*

Sure it is redundant, but as long as there is Copy-Paste, I don't mind the redundancy! :)

T-90
Thursday, February 19, 2004

I name my parameters in the header file because it is a lot more concise and useful than a long list of doxygen comments.

Also most editors provide a useful tooltip of syntax completion, and the names really really help.

i like i
Thursday, February 19, 2004

Ask yourself the following question:

When I want to take a look at the interface of a class, what do I prefer:
1. Open the header file, and find all the information I need right there, in a few dozen lines?
2. Ignore the header file, go straight for the implementation, and navigate around 100s of lines of code?

If you chose answer #2, you may delete the args names in header files :)

Just in case you're wondering, I chose answer #1, and I always name args in header files.

Paulo Caetano
Thursday, February 19, 2004

All good points. Also it probably makes it easier to change the method sig- just cut and paste from the definition (and remove the "Classname::"). Thanks for the feedback.

Ken
Thursday, February 19, 2004

I agree with Paulo except for one case which is when creating Windows message handlers with VC++. The damn things are always called wParam and lParam anyway. What I often end up doing is breaking the real arguments out of those parameters, adding an extra function to do the real work, and calling that from the message handler.

Thursday, February 19, 2004

I not only name my parameters in the .h file, but I document the class in the header as well. One good thing about this is, in vim, I can put the cursor on a class name, hit ^], and go to the class definition. As I'm not usually after the definition, but trying to remember if I called it maxFoo or maximumFoo, that's a win for me. It also helps to see the docs at the same time.

Second reason is if my company ever decides to ship my code as a library then it's no work for me. The class is already documented in the header file, which needs to go with the library anyway.

Snotnose
Thursday, February 19, 2004

I had a bug last week where a function said it took fn(double periodicity, double periodlength) in the header, but then in the source had switched to fn(double periodlength, double periodicity). It's completely legal to rename the arguments between the header and the source, so no warning of any sort.

C++ really drives me nuts on what it makes you repeat: static, virtual, const; What it won't let you repeat: default values for parameters; and then with the parameter names, it won't even tell you if you didn't repeat them correctly!

I'm definitely for naming the parameters in the header. If you also put in comments about what the function is for, the header becomes a useful developer's document summarizing the interface, its purpose, and usage.

Keith Wright
Thursday, February 19, 2004

I prefer to leave names out when they don't add anything:
void OnClick(Button* button);

Is just 7 key strokes more than:
void OnClick(Button*);

But, as Keith said if you have
double DoSomeMagic(double, double);

Then make sure that the names are useful:
double DoSomeMagic(double a, double b);
doesn't count!

Rob Walker
Thursday, February 19, 2004

> I prefer to leave names out when they don't add >anything

Oh jeez, now you want me to actually think;)

Sounds like the consensus is, generally speaking, to name arguments. Basically b/c the header should be a reasonably helpful source of information for someone wanting to use the class. I'll buy into that.

Ken
Thursday, February 19, 2004

Plus if you would use VS.Net or VS.2003 you get nice intellisence comments about functions in autocomplete function dropdown. Since header takes priority not having parmeter's names will be inconvinient.

Ohhh and swapping arguments that have the same type should be considered as serious crime :)

WildTiger
Thursday, February 19, 2004

: Plus if you would use VS.Net or VS.2003 you get nice
: intellisence comments about functions in autocomplete
: function dropdown. Since header takes priority not having
: parmeter's names will be inconvinient.

Which reminds me -- for managed C++ I need to get in the habit of putting argument names back in 'cos they end up in the meta data from the class definition.

Seeing stack traces in an exception that include
void foo(int __unnamed_38834)
or something like this don't look so good.

Rob Walker
Thursday, February 19, 2004

I write the code in the header files anyway. It speeds development when functions are changing rapidly.

If people around me are being anal about the amount of code in the headers, I have perl scripts to migrate the functions to the C file when I'm done.

Katie Lucas
Friday, February 20, 2004

How exactly does it speed development to put tons of code in headers? You are simply trading the once-in-a-while cost of making two edits (not exactly difficult) for the very common cost of having to recompile many dependancies when you make a change that doesn't impact the interface

MikeMcNertney
Friday, February 20, 2004