lclint-interest message 88
From email@example.com.EDU.AU Mon Jul 8 11:12:05 1996
Date: Mon, 8 Jul 1996 16:31:54 +1000 (EST)
From: Richard A OKeefe
Cc: firstname.lastname@example.org, email@example.com
Subject: Re: Formal array size check request > It is a bad idea to put formal parameter names in prototypes. > To an audience concerned with writing correct code, I don't need > to explain why.
Well, I like to think that I am concerned with writing correct code, but I
still need to have this explained.
I know that the formal parameters are ignored in the function
"It ain't what we don't know that kills us,
it's what we do know that ain't so."
Where _did_ you get the idea that formal parameter names are ignored?
THEY ARE STILL SUBJECT TO PREPROCESSING.
That is the problem.
For example, suppose I put
extern void deluset(uset_ty set);
in a header. Then along comes an innocent user, and does
#define not_set 0
#define set 1
<< 100 lines >>
Suddenly, in the guts of a header which the innocent user
(a) has no reason to look at, and
(b) HAS NO POWER TO ALTER,
the compiler complains about a syntax error. The innocent user looks
at the header, and sees nothing wrong. Poor innocent user; no idea
that the _compiler_ thinks the header now says
extern void deluset(uset_ty 1);
Now in this example,
- the function name 'deluset' IS part of the documented interface
- the type name 'uset_ty' IS part of the documented interface
- the formal parameter name is NOT part of the documented interface.
In short, as far as *usage* is concerned, the formal parameter names
have only nuisance value.
but I thought that they were a good idea from the point of view
of making the code understandable.
If you are relying on function prototypes instead of proper documentation,
I pity you. There is *much* more information you need to use a function
properly than just the parameter names!
For instance, for which of the following prototypes will a coder
most likely get the parameter order correct?
char *strtok(char *, char *)
char *strtok(char *token_string, char *separator_string)
Well, I would actually write
extern char *strtok(char *, char const *); /*2.5.1*/
because the 'const' in the second parameter is required by the standard.
For what it's worth, that's _exactly_ the prototype in
/usr/include/string.h on this Solaris 2.5.1 system, the one I've commented.
And you know what? THE ABSENCE OF PARAMETER NAMES FROM THE PROTOTYPE
DOES NOTHING TO HINDER CODING. And do you know why? BECAUSE PEOPLE LOOK
AT THE MANUAL PAGE, NOT THE HEADER!
In fact, the UNIX manual page illustrates perfectly the danger of relying
too heavily on prototypes. Here's the prototype in the manual page:
char *strtok(char *s1, const char *s2);
I for one find "s1" and "s2" no help at all in figuring out which
parameter does what. If the manual page didn't have a paragraph of
explanatory text, I wouldn't know _what_ to do with that function.
If then the function is defined as
char *strtok char *s1, char *s2)
what harm has been done?
Well, even apart from the syntax error, quite a lot. The persone who is
_implementing_ the function is just as much a 'coder' as the person _using_
it. Good parameter names and good comments are a big help while writing
If you want parameter names in your prototypes for human readers,
there is a way you can have names in perfect safety:
For example, my own string library back in the dear old K&R days had
function declarations like
extern char *strtok(/*char* buffer, char*separators*/);
I suppose there would be a problem if somebody changed the order
of the parameters in the definition without changing them in the
prototype. There would be no check which would find this
change. On the other hand, if there are no names, there is
still no check to find the change, and coders who mistakenly
used the old parameter ordering are still in big trouble when
they link to the function using the new ordering.
Changing parameter order has nothing to do with the case, tra-la.
You keep on assuming that the prototype (hidden away in a header which
is chiefly of interest to the compiler)
(a) is and ought to be separately written, not derived from the code
(b) is and ought to be a primary source of documentation.
(c) cannot provide information by means of comments.
I vehemently deny all three propositions. I claim that
(a') the best way to "write" headers would be to have a tool which reads
a file foobar.c and spits out into foobar.h suitable declarations of
the externally visible identifiers. On a SVr4 system, this could
be done by parsing the DWARF information in the ELF file, but it's
if anything easier to parse C... Again on a SVr4 system, this could
be done by parsing the cscope.out file, but that basically _is_ C,
so there's little to gain.
(b') a header is primarily a device for instructing a *compiler* about the
interface of a module; it need only contain the information that the
compiler needs. Humans need more information and better organised.
At a *minimum*, structured comments extracted and formatted by a tool
such as c2man (it's free, and very handy) should be used. (If you
use Emacs as your editor, find-definition can take you to the function
definition where you can read these comments and not just be stuck with
the driblet of information misered out in a prototype)
(c') comments are a perfectly good way of including extra information in
a header if you really want to, and they AREN'T subject to preprocessing
so AREN'T a danger.
> Many students are putting prototypes inside functions.
> I don't suppose I need to explain the dangers of this either.
Um, yes, please do. Am I correct in believing that the problem
is that the student expects the extern declaration to be visible
only within the block in which is is defined, while in fact it
is visible for the rest of the translation unit?
There are actually four dangers.
One is that the rule is, as you point out, astonishing.
Another is that you cannot trust compilers to get it right.
Another is that some useful tools (cscope for one) don't understand them.
The last is that it is simply in the wrong place, where the
compiler cannot check it.
The last one is perhaps the major problem: the habit of putting
function prototypes inside functions is also the habit of *not* putting
them in headers and *not* arranging for the compiler to include the header
when it translates the module exporting the function. In fact, I have
*never* seen such a function prototype which was still valid after
nontrivial maintenance. (I have converted >100 000 lines of C code from
K&R to ANSI, and one of the big problems is nested function declarations
for standard functions that don't even have the right result type any more.)
Our rule here is that prototypes for globally visible functions
must be placed in header files. Then this header file must be
included by any code which uses the function, and especially by
the code which defines the function.
This is my rule exactly, and the rule of cautious C programmer.
Is this what you require of your students?
I am a fair imitation of an expert programmer.
I am not that hot at playing a teacher.
So this year I was tutoring in the C course, not teaching it.
There are two sad facts of life you have to deal with in a C course:
(a) you can *tell* students till you are blue in the face to do something,
but if you don't *enforce* it, most of them won't *do* it.
In the last assignment this year, several students handed in C++ code,
not C code, despite the fact that their DOS C++ compilers have an
"ANSI C" switch.
I told the students in my tutorial group
(a) Use lint.
(b) Here is a shell script in your course directory call glint;
it runs gcc with all warnings enabled. Use it.
(c) Here is an 'indent.pro' file; please run indent over your code
before handing it in.
Point (c) provoked *amazing* hostility, even though I provided written
justification for each of the indenting decisions in the indent.pro,
a written explanation of why it was in their best interests for me to
be able to read their code, and a clear explanation that this did NOT
mean that they had to WRITE their code in that style, only indent a
copy just before handing it in. Needless to say, the students who
were most vociferous in protesting against this "fascism" were the
ones with no coherent indentation style of their own...
Points (a) and (b) didn't provoke hostility, but instead total apathy.
There were 5 assignments in the last semester. After each one, I
explained to the students in my tutorial group how they could have
used 'lint' to find their mistakes before I did. About 10% of students
were handing in lint-clean code by the end of the semester.
(b) Most C textbooks are incredibly bad. Kelley & Pohl's books are really
outstanding on the badness scale. There is no folly so great that
students will not copy it from a textbook, however warned. I have seen
more C textbooks than I really want to, and almost none of them explain
header usage well or provide good examples of header usage.
For example, almost all the students were following the pattern
with one header file for the whole program, despite the fact that
assign3.c (or whatever it was called) exported nothing (except main).
Why did they do this despite what they were told in class?
If a textbook says one thing and a teacher says another, they go with
the textbook. (Except for the ones who don't buy the textbook, but
that's another story.)
University of Virginia, Computer Science