Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

closed as primarily opinion-based by gnat, MichaelT, jwenting, Caleb, GlenH7 Sep 4 at 2:42

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

1  
@gnat I am not asking what to name something, I am asking how to start a sentence with a function name. –  user3462295 Sep 1 at 19:12
11  
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 1 at 23:09
6  
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 2 at 0:02
1  
There are some remarkably active programmers over on English.SE (tchrist... not so much 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. –  MichaelT Sep 2 at 1:35
2  
This question appears to be off-topic because it is English language and usage, and we have an entire StackExchange site for that. Indeed, there are at least four similar questions there. Also, different answers may be equally valid depending on where the writing appears, etc. –  Caleb Sep 3 at 15:56

9 Answers 9

up vote 84 down vote accepted

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.

share|improve this answer
    
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 1 at 19:12
22  
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 2 at 8:41
3  
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 2 at 18:27
1  
@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 Johnson Sep 2 at 22:23
3  
@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. –  Cory Sep 3 at 13:29

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.

share|improve this answer

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.

share|improve this answer
3  
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 2 at 10:09
2  
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. –  kapep Sep 2 at 13:24
1  
@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 2 at 13:54
2  
@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" oracle.com/technetwork/java/javase/documentation/… –  kapep Sep 2 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 2 at 21:38

You can start sentence from description:

The function fread[…]

The method fread[…]

The property breadColor […]

share|improve this answer
    
@Zack: President Obama. –  Marc van Leeuwen Sep 3 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. –  Zack Sep 3 at 14:00

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

share|improve this answer
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 2 at 2: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 2 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 2 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 2 at 17:16
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 3 at 3:13

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.

share|improve this answer
    
I do like your answer. Doing such does make writing about functions look better. –  user3462295 Sep 3 at 21:43

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.

share|improve this answer
3  
No! that would make it a run-on sentence or comma splice. Very poor grammar. A semicolon would be OK. –  Martin McCallion Sep 2 at 10:51
    
So using a comma don't always work; but why use a comma? –  reinierpost Sep 2 at 10:55
    
It's not a comma. It's a semicolon; a proper use of a semicolon at that. –  ckuhn203 Sep 2 at 22:49
1  
I would personally use a colon here instead of a semicolon (although it reads well with a semicolon too). –  Marc van Leeuwen Sep 3 at 12:21

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.

share|improve this answer

If you want to start your sentence with an UPPERCASE letter, change your function's name first letter to uppercase. Example:

  • Find and replace: fread() with Fread() (Replace all)

This will replace the function name and all function calls.
Just my opinion.

share|improve this answer
1  
in some programming languages / projects, changing like you recommend would break code style conventions and lead to the code that is harder to read and maintain –  gnat Sep 2 at 12:49
3  
@gnat - This must be a joke... –  sixtyfootersdude Sep 2 at 13:23
2  
You could also replace fread() by _fread(). There is no uppercase underscore. :-) –  Florian F Sep 2 at 14:02
4  
In go, such a change would make a private method public. This would not be an acceptable change. –  MichaelT Sep 2 at 15:58
4  
... or its part of part of a standard. One cannot change fstat() to be Fstat(). –  MichaelT Sep 2 at 17:47

protected by Thomas Owens Sep 2 at 14:10

Thank you for your interest in this question. Because it has attracted low-quality answers, posting an answer now requires 10 reputation on this site.

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.