Beginning a sentence with a function name?

Question

Occasionally while typing something up that relates to a case-sensitive programming language I end up starting a sentence with a function name. Now the rules of English state that the first word in a sentence needs to be capitalized; the function name is lowercase, though. If you are wondering what could I be saying that would result in the first word being a function name, take this example:

Your fread implementation is broken. fread needs to return how many bytes were read.

I understand that I could change the second instance of fread to It but I want to know the best way of handling this other than just rewriting the sentence. Should I capitalize the function name? The only way I would like to hear "rewrite the sentence" as an answer is if starting the sentence with a function name violates some English rule that I am not aware of. Edit: I really thank everyone for these answers. They have changed and improved my insight into the issue. I have learned quite a bit from this. I am very surprised that I did not think of these simple but good solutions.

I do think my stance on alternating the sentence was too tough and now I realize due to these good answers that overall altering the sentence appears to be the best option for dealing with these cases be it adding parenthesis after the function or saying The function before the function name and if available using formatting for the function name.

Answer 1

In typography this is generally handled by using a different rendering, whether or not it's the start of a sentence, to indicate that what's hitting the eye is not just a word in the sentence but a special entity.

Your fread implementation is broken. fread needs to return how many bytes were read.

Depending on how formal a document is, it can adopt the same approach. In any case doing so eliminates the issue you identify, so you may wish to use it for that reason alone.

In the plain text world (as noted by several in comments and other answers), appending parentheses to function names helps a bit, but since we also need to refer to entities that don't take parentheses, this has only limited value. In general, short of adopting a convention of surrounding the text with special characters like brackets and asterisks, in the plain text world there's little option but to sidestep the issue by restructuring the sentence.

Answer 2

If there is an absolute requirement to start each sentence with a cap, then simply replace fread with "The fread function" wherever it starts a sentence.

Answer 3

If you don't have typographic means to distinguish (as per another answer), and maybe even if you do, it can be useful to indicate that you are talking about a function by using parens:

Your fread() implementation is broken. fread() needs to return how many bytes were read.

This helps with "explaining" why it is not capitalised at the beginning of the second sentence, and also helps (in the first sentence) to understand why the proper noun (name of a function) is not capitalised there either. Since (as a proper noun) it arguably should have been.

("arguably" because we could argue whether fread() is a generic noun or a proper noun).

Overall, the use of parens helps the reader's brain understand why strange words appear and what they are.

Answer 4

You can start sentence from description:

The function fread[…]

The method fread[…]

The property breadColor […]

Answer 5

You can compare this to inline mathematics in publications. You will very rarely see sentences starting with a variable or other inline math.

Thus, I conclude, you should avoid function names in the beginning of a sentence.

Maybe this question provides further details: Is it okay to start a sentence with a Greek letter (variable)?.

Answer 6

The Linux man page for fread(3) that others linked is a great example of four common solutions.

1. Begin your sentence with "The function foo" or "The foo function". "The function fread needs to return ...".
2. Mark the function name with extra characters according to the convention used by your programming language community. In the case of C, an empty pair of parentheses, so "fread() needs to return ...".
3. Use typography (bold , fixed width characters or italics) to highlight the function name, as: "fread needs to return ..."
4. On systems that use man, if your function has a man page, refer to the chapter of the manual in parentheses. So "fread(3) needs to return ..."

All four approaches will be instantly recognizable by hackers, and you should be able to choose one that matches your house style or your personal voice.

As you said, you cannot rely on typography to highlight your function name. Markdown's syntax is meant to make readable documentation even when a markdown interpreter is unavailable, so by all means surround your function name by a pair of backticks. (This is, I guess, a combination of options 2 and 3.)

Option 2 varies according to programming language. For example, Ruby and Smalltalk docs often precede instance method names with a hash, like #fread. Meanwhile, Lispers might prefer the function name to be bare, but will understand if you write a skeleton function call, such as (fread ...) or (fread). Rinse and repeat for all languages you document.

Answer 7

I am only going to answer for the specific example given:

Your fread implementation is broken. fread needs to return how many bytes were read.

Just replace the first full stop (Period) with a semicolon:

Your fread implementation is broken; fread needs to return how many bytes were read.

Answer 8

I know this has already been answered, and the accepted answer's pretty good, but I just want to clarify something.

In proper English grammar, the bottom line is this: Sometimes proper nouns are given names that do not start with a capital letter, and in most such cases, they are every bit as attached to not being capitalized as "normal" proper nouns are to being capitalized. In such cases - which would certainly include most function names in C-descended languages - you absolutely do not capitalize the name, even at the beginning of a sentence. In fact, it is bad English grammar and spelling to do so. This is actually a part of the same principle as to why it's correct to spell Sony's gaming console "PlayStation", but not "Playstation".

There are other cases in which a proper noun is not supposed to be capitalized by default, and yet it can be (and should be) when used at the beginning of a sentence. The name of the language brainfuck is an example of this. Functions in C-descended languages are not. myFunc() and MyFunc() are two totally different things in languages like that, and starting a sentence with the word "MyFunc()" will only refer to the latter, not to the former. In VB.NET though, this is a grey area, since these two functions would be the same thing in that language, although function names would also retain user-specified capitalization schemes, on some level or another.

Also, even though English rules are set in stone in this case, they tend to get kind of hazy around things like this as a rule. English wasn't designed with things like this in mind, so for other things like this, there is room for improvisation.