Re: capitalizing function names

[Lisa Kaytes <lisa_cavaliere-kaytes -at- WARREN -dot- MENTORG -dot- COM>]

> Do you separate it with quotes or anything? I have found this technique
> to be woefully inadequate when functions names are common nouns or verbs.
> Sentences become extremely difficult to read because the function name
> is easily misread:

>         In this case, contours is used instead of gradients, because map
>         is completed.

I can see how you would find this technique inadequate without a modifier.
To make the sentence clearer, I would write it as:

        Because the map function is completed, the contours function is used
        instead of the gradients function.

Of course it all comes down to preferences. You might think the
extra words are more distracting than the quotes or the bolding. I
can`t use capital letters or initial caps because the language I am
documenting is a derivative of C and is case sensitive. I did try
the bold/font options, but when several functions appeared on the same
page, it looked too busy (and several inhouse users agreed). We
settled on the wordier explicit approach.


> Is there anyone out there who feels that common nouns and verbs should not
> be used as program, function, or command names because of this potential
> for confusion when describing the system? In defense of this convention, I
> will argue that it is better to use such descriptive terms than arcane, made-
> up ones, because it makes them easier for users to remember, which makes the
> system seem friendlier, which in the long run, should make our jobs easier.


I think developers should use whatever term most accurately summarizes the
purpose of a function, even if it is a common noun or verb. Such terms
can pose some formatting problems for writers, but overall they should
make the system easier to use.