|
|
|
|
| Tutorial |
This is probably what comes to mind first: an interface that accepts a “common sense”
list of parameters, namely the date in day/month/year variables and the time in
hours/minutes/seconds, as well as a string for the description of an appointment.The
functions don’t return anything; their names are speaking.
Speaking, yes—but well-speaking? add_an_event() is speaking for sure, but nevertheless
a bad choice for a function like this. First of all, the function will be meant for
global access; that is, it’s a main element for the API. As such, it should identify itself
clearly as belonging to this API as well, by using a name prefix.
What could this prefix be called? calendar and scheduler are good choices; in this
example, we’ll use calendar (see Listing 1.11).
Listing 1.11 Renamed function prototypes.
void calendar_add_an_event(int day, int month, int year, int hour, int minutes,
➥int seconds, string description);
void calendar_delete_an_event(int day, int month, int year, int hour, int minutes,
➥int seconds);
Now we’ve got a prefix, but the names are still unsatisfactory.The an in
calendar_add_an_event() and similarly in calendar_delete_an_event() isn’t really
needed; it’s a relic from choosing names that are “too speaking.” Leaving out words
such as a, an, and the is a good practice when choosing function names; most of the
time such words use up space in the name but don’t make a big difference because
they have no explanatory function. Moreover, they should definitely be avoided when
choosing variable names; in variable names, it makes absolutely no sense to choose a
name such as $a_key or $the_key, since the fact that it’s a key is obvious. It makes
more sense to select a name that explains what key; for example, $last_user_key.
Listing 1.12 shows the newly renamed functions.
Listing 1.12 Final function names.
void calendar_add_event(int day, int month, int year, int hour, int minutes,
➥int seconds, string description);
void calendar_delete_event(int day, int month, int year, int hour, int minutes,
➥int seconds);
On to the next question.These functions carry a huge parameter list. Is this necessary?
The parameters as they are now have been chosen intuitively, according to the common
date format that separates day, month, year, hour, minute, and second. However,
interchanging information with such an interface is a kludge. Functions should hardly
ever need to accept more than five parameters. If there are more parameters to be
passed, you should think about passing them using a structure. Structures help to keep
the interface clean, which is sometimes a much more worthwhile goal than avoiding
the extra overhead that structures impose when initializing and/or modifying them.
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
