43

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.

user3462295
  • 521
  • 4
  • 9
  • 1
    @gnat I am not asking what to name something, I am asking how to start a sentence with a function name. – user3462295 Sep 01 '14 at 19:12
  • @JanDoggen I though about doing that but decided that I would be best here as there may be many non-programmers over there. – user3462295 Sep 01 '14 at 21:36
  • 13
    There is a related convention in mathematics that one should avoid beginning a sentence with a variable name or formula. This is despite the fact that we do have a typographical convention that variables and formulas are rendered in italics to set them off from text. One would avoid writing "Let *x* be a power of 2. *x* is positive, so..." The usual fix is to rephrase or add some filler word: "Now *x* is positive" or "We have that *x* is positive" or something of the sort. – Nate Eldredge Sep 01 '14 at 23:09
  • 9
    An identifier from a programming language should be treated as a *foreign* word and shouldn't be subject to the same rules of English. – Rufflewind Sep 02 '14 at 00:02
  • 1
    There are some remarkably active programmers over on English.SE ([tchrist](http://english.stackexchange.com/users/2085/tchrist)... not so much [Eric Lippert](http://english.stackexchange.com/users/6319/eric-lippert)) - but it depends on the type of answer you want. We're writing this as programers on a programer focused site. If you're more interested in the formalities of technical writing, journal guidelines, and proper English sentence structure, you may wish to reconsider your target expert audience. –  Sep 02 '14 at 01:35
  • 1
    Okay, I understand the larger question so I am not going to post this as an generic answer, but for simple cases like your sample (and this may handle a large percentage of actual instances), you can use punctuation. "Your fread implementation is broken-- fread needs to return how many bytes were read." or "Your fread implementation is broken: fread needs to return how many bytes were read." – Kristian H Sep 02 '14 at 17:55
  • Interestingly, old Unix manual pages (as well as Plan 9) [_did_ capitalize the function names](http://plan9.bell-labs.com/magic/man2html/2/fgetc), but over time this [changed](http://man7.org/linux/man-pages/man3/fwrite.3.html). Also mentioned in the [Jargon File](http://www.catb.org/jargon/html/writing-style.html). – user1686 Sep 03 '14 at 07:28
  • I'd just rephrase the sentence to avoid the problem (e.g. "The fread function needs to..."). – Brendan Sep 03 '14 at 07:52
  • How about 'Your fread() implementation is broken. fread() needs to return how many bytes were read.'? –  Sep 03 '14 at 09:32
  • 2
    This question appears to be off-topic because it is English language and usage, and we have an entire [StackExchange site](http://english.stackexchange.com) for that. Indeed, there are at least [four](http://english.stackexchange.com/q/114387/7225) [similar](http://english.stackexchange.com/q/54745/7225) [questions](http://english.stackexchange.com/q/21295/7225) [there](http://english.stackexchange.com/q/28383/7225). Also, different answers may be equally valid depending on where the writing appears, etc. – Caleb Sep 03 '14 at 15:56

8 Answers8

88

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.

Reg Edit
  • 954
  • 8
  • 11
  • Yes I do see your point, it does still fell awkward but less awkward. However I understand that feelings are not always inline with rules of grammar and writing. I am not sure if there is a better way to handle this so I shall accept your answer unless someone comes up with something better. – user3462295 Sep 01 '14 at 19:12
  • 26
    I often just italicize for things like this - you should *always* maintain the casing of case-sensitive terms, regardless of where they are in a sentence, IMO. `fread` is not a word; it is a symbol representing an entity. It's not subject to grammar. – Ant P Sep 02 '14 at 08:41
  • This is exactly why things like StackExchange allow for marking "code" as formated `like this` – joshin4colours Sep 02 '14 at 15:38
  • 4
    And... what do you do if you have to deal with plain text? Like in a small .txt help file, or a plain text email? I suggest including that scenario as well to your answer. – Ellesedil Sep 02 '14 at 18:27
  • 2
    @Ellesedil In that case, I'll usually suffix it with `()` or `(...)` to indicate it's a function. But that doesn't always work, especially when dealing with variables and such. What I do then is wrap the name with `\`` (tick character) to indicate it's code. – Cole Tobin Sep 02 '14 at 22:23
  • You mean rendering _identifiers_ rather than **keywords**; I don't know no any language where _fread_ is a keyword. By the way, in prehistoric times programs were sometimes published (in journal for instance) with keywords in boldface and identifiers in italics. It looks beautiful, but one cannot stop progress. – Marc van Leeuwen Sep 03 '14 at 04:13
  • @MarcvanLeeuwen you're right, I've edited my answer to avoid an explicit term, as it's a broader principle. – Reg Edit Sep 03 '14 at 07:22
  • `fread` is what's known as a "literal", it is a symbol. If you capitalise it you corrupt the symbol and it just becomes a part of your narrative. You don't have the "right" to capitalize it as it exists separately, independently, apart from your own description. As other commentators have noted, you might usually change rendering using *italics* (the standard for typed documents) or markup such as SE's `backticks` (where this is available). Where you only have standard latin characters available (e.g. in code comments) you should use 'single quotes' i.e. 'fread' needs to return how... – robert Sep 03 '14 at 09:21
  • 4
    @Ellesedil I've taken to using the markdown syntax for indicating code elements, even in plain text contexts such as comments. It's the only time I've ever needed to use a backtick symbol when writing plain English. – Keen Sep 03 '14 at 13:29
  • @Ellesedil good point, I've added a note about plain text. – Reg Edit Sep 03 '14 at 13:32
  • @user3462295 Capitalization is a matter of orthography, not of grammar. – tchrist Sep 04 '14 at 00:25
53

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.

x-code
  • 1,058
  • 8
  • 11
21

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.

GreenAsJade
  • 426
  • 2
  • 13
  • 5
    Using parens also helps reducing the text redundancy. Instead of "the function fread" you can say just "fread()". And it is also useful if you have a sort of highlighting to emphasize the difference between things like variable names and functions. – Paul92 Sep 02 '14 at 10:09
  • 3
    I think parenthesis only add more confusion. `fread()` could be a call statement. Or it could be referring to an overloaded function with no parameters. – kapex Sep 02 '14 at 13:24
  • 4
    @kapep Generally in documents referring to code, `func_name()` is read as "a function by the name `func_name`", regardless of whether or not the actual function itself has any parameters. – Eric Finn Sep 02 '14 at 13:54
  • 3
    @EricFinn In my experience it generally it refers parameterless functions, but it surly depends on the language and its conventions. For example, the official Java comment guidelines discourage the use of parentheses: "When referring to a [specific form of a method], use parentheses and argument types. [...] However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method" http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html – kapex Sep 02 '14 at 15:47
  • 3
    While adding a visual clue is certainly a good idea (the best being a dedicated font or otherwise highlight), I agree with kapep that appending empty parens is a really problematic choice, because in every language I know `f()` means something different from `f`. Why not _surround_ the name with some suitable character, e.g. markdown-style \`fread\` (that's what I tend to do in VCS commit messages)? Or simply (fread). Of course, any such thing should be done consistently, not just for functions at the beginning of a sentence. – leftaroundabout Sep 02 '14 at 21:38
  • 1
    One must distinguish between a function itself and the value (result) delivered by a function. Using parentheses to indicate the function itself is an absurd convention, since in programming it is quite the opposite: if you want to pass (a pointer to) `f` itself to a function `g` you would write `g(f)`, but `g(f())` would mean passing the result returned by (the parameterless function) `f` to `g` . – Marc van Leeuwen Sep 03 '14 at 12:13
  • 1
    Absurd or not, it is quite common, convenient, and natural to read in the way that @EricFinn described. I think it only _appears_ absurd if you insist on rigidly applying an in-program interpretation that manifestly does not exist in the context of an english sentence containing an embedded function name. Nobody with an ounce of nous would interpret the sentence "fread() needs to return the number of bytes it read." as meaning "the instance of the 'fread' function that takes no parameters needs to..." – GreenAsJade Sep 03 '14 at 12:29
10

You can start sentence from description:

The function fread[…]

The method fread[…]

The property breadColor […]

David Sergey
  • 513
  • 3
  • 11
  • @Zack: President Obama. – Marc van Leeuwen Sep 03 '14 at 12:16
  • @MarcvanLeeuwen Titles are a special case. (Also "Queen Elizabeth", "Mister Rogers".) I don't have a proper analysis off the top of my head, but intuitively I think they're considered part of the name rather than a category tag. – zwol Sep 03 '14 at 14:00
8

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)?.

Community
  • 1
Lukas
  • 189
  • 3
  • 3
    +1. In *Mathematical Proofs* (Chartrand et al., 2000), whose Chapter 0 is a true fount of good advice for mathematical writing, the very first rule under *Using Symbols* is "Never start a sentence with a symbol." (The example is a sentence that starts with an equation; the authors suggest prefacing it with "The equation ___".) Although not all mathematical writing advice necessarily applies to writing about source code, I think this is one bit that does. – ruakh Sep 02 '14 at 02:52
  • 1
    I'm not sure I agree with the analogy. Symbols like $x$ are transient to an equation so it's weird to refer to them as though they have a global meaning. If a symbol like $\pi$ starts a sentence, I would feel comfortable as a reader. – djechlin Sep 02 '14 at 14:21
  • 1
    @djechlin I'm not sure that starting a sentence with a symbol implies that it has a global meaning, or in fact has anything to do with that. – Kyle Strand Sep 02 '14 at 17:13
  • @KyleStrand it'd be nice to know why you should never never start a sentence with a symbol. "$\pi$ is..." v. "The mathematical constant $\pi$ is..." - you choose. – djechlin Sep 02 '14 at 17:16
  • @djechlin I think it's primarily for stylistic reasons; its simply considered better style to embed non-Latin characters in English sentences rather than start sentences with them. – Kyle Strand Sep 02 '14 at 17:18
  • 1
    @djechlin: One reason is that if the previous sentence ends with math, the math at the start of the following sentence may look like part of the same formula with a dot in between. (This is even more of a problem with commas.) Another issue is that since variable names are usually lower case, the reader's eye loses the visual cue of looking for a capital letter to find the start of the next sentence. – Nate Eldredge Sep 03 '14 at 03:13
  • @djechlin: "Scoping" in mathematical writing is not so simple as you suggest. It's not the case that "universal constants have global scope and everything else has scope local to the equation where it appears". Variables can have pretty much any scope the author intends, but the reader has to understand it from context. The author can start a paper by writing "Let $x$ be a real number" and it will typically have global scope; future references are assumed to refer to the same $x$. But anyway, this is not really related to the convention under discussion. – Nate Eldredge Sep 03 '14 at 03:20
3

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.

dcorking
  • 586
  • 4
  • 13
2

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.

EdHunter
  • 137
  • 2
0

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.

Panzercrisis
  • 3,145
  • 4
  • 19
  • 34