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.

I'm sure many of us have seen method names like this at one point or another:

  • UploadTheFileToTheServerPlease
  • CreateATemporaryFile
  • WriteTheRecordToTheDatabase
  • ResetTheSystemClock

That is, method names that are also grammatically-correct English sentences, and include extra words purely to make them read like prose. Personally, I'm not a huge fan of such "literal" method names, and prefer to be succint, while still being as clear as possible. To me, words like "a", "an", and "the" just look plain awkward in method names, and it makes method names needlessly long without really adding anything useful. I would prefer the following method names for the previous examples:

  • UploadFileToServer
  • CreateTemporaryFile
  • WriteOutRecord
  • ResetSystemClock

In my experience, this is far more common than the other approach of writing out the lengthier names, but I have seen both styles and was curious to see what other people's thoughts were on these two approaches.

So, are you in the "method names that read like prose" camp or the "method names that say what I mean but read out loud like a bad foreign-language-to-English translation" camp?

share|improve this question
7  
I have never seen methods with names like WriteTheRecordToTheDatabase. If someone checked this in they'd get a serious talking-to. –  Tim Robinson Sep 16 '10 at 8:30
11  
"Please"? Wow –  configurator Sep 29 '10 at 23:54
3  
I'd just like to add that wordpress has template helper functions like "the_contents()," "get_the_post()," etc. It bugs the crap out of me. –  Carson Myers Jul 12 '11 at 7:12
1  
@Carson Myers Hah, that's a perfect real-world example of this. I must have suppressed the memories of the last time I looked at WordPress code :-) –  Mike Spross Jul 13 '11 at 1:36
add comment

6 Answers

I'll agree that prose methods suck with one exception:

Unit Test Cases

These are generally never called in your code and show up in test reports. As such, it's handy to have readouts with a bit more prose:

  • AddingACustomerOrderFailWhenCustomersIdIsInvalid : Failed
  • OutOfBoundsPriceReturnsAnError : Passed
  • CanDeleteAnEventFromASeason : Passed

Even this should be done sparingly, but I can see it as at least one case where grammatical additions can make it a little easier to express what passed and what failed. This is, of course, unless your language/framework provides a good mechanism for test-descriptions in the test readout other than method names, in which case ignore this one too.

share|improve this answer
1  
+1 for a good example of where prose method names can actually be beneficial. It's funny, because now that you mention it, I have done this specifically when writing unit test names, and specifically so I knew what the heck the test was doing when I ran them later. –  Mike Spross Sep 16 '10 at 6:32
    
That's useful, and fits into Roy Osherove's suggested MethodUnderTest_Condition_ExpectedBehaviour unit test naming convention. e.g. AddOrder_WithInvalidCustomerId_Fails, CreateItem_WithOutOfBoundsPrice_ReturnsError and DeleteEvent_EventExistsInSeason_Succeeds –  StuperUser Jun 2 '11 at 11:47
    
@StuperUser for expected behaviour, your have actually put expected test outcome and thus I have no idea what the method is supposed to return. –  danRhul Mar 1 '12 at 12:26
    
@danRhul Fair point, I wasn't clear enough; .._AdditionFails and .._DeletionSucceeds should be better. I did put the method outcome, but as you point out they could be confused with testing pass/failure terminology. –  StuperUser Mar 2 '12 at 18:38
add comment

To paraphrase Lawrence from Office Space...

No, no, man, I do believe that if someone I worked with around here named a function 'UploadTheFileToTheServerPlease', he'd get his a-- kicked, man.

share|improve this answer
add comment

Such "long" names do not sound like prose. When alone—perhaps, but accompanied with the rest of the code, they just make more of a mess. Check it out:

bool ResultOfTheUpload
      = UploadTheFileToTheServerPlease(TheNameOfTheFile, TheServersAddress);

Yuuuuk!..

This isn't a valid English text, and in no programming language will it look like one. So there's no sense in spending bytes on articles.

share|improve this answer
1  
A good example of why I dislike this approach so much! When I wrote the question, I was only focusing on the method names by themselves sounding like prose, but I agree with you: it's pretty hard to make the calling code actually read like prose, so no point in making individual function names sound like written English. –  Mike Spross Sep 16 '10 at 6:29
2  
I suggest bool ResultOfTheGentlyUploadOfTheFileToTheServer –  Lorenzo Sep 17 '10 at 9:48
    
I have worked with a person who created company standards where 'theVariable' and 'aMethod' had to be followed. This same person also liked to have all of lines of code line up vertically. –  Chris Jan 28 '11 at 4:36
add comment

From programmers perspective "UploadFileToServer" makes more sense and easier to read and understand than "UploadTheFileToTheServerPlease".

More than English grammar, readability and understandability matters more in programming!

share|improve this answer
    
Totally agree..if I read the code written in first style for a few days I am sure it will drive me crazy.. –  Naveen Sep 16 '10 at 5:21
    
@Naveen: I've worked with code like this, and the first chance I got I renamed all those methods. And I'm not sure if it was just the developer or not, but I think there is a tendency to make functions do multiple things when you write them as sentences, i.e. UploadTheFileAndProcessItAndEmailTheOrdersToTheCustomers, although hopefully nothing quite that bad in real life. –  Mike Spross Sep 16 '10 at 6:50
    
@Mike Then I would refactor the method to 2 different methods ;) –  Tech Jerk Sep 24 '10 at 12:14
add comment

Given how many typos my life features, I'd end up with

* UploadTehFileToTehServerPleaz
* WriteTehRecordToTehDatabase
* ResetTehSystemClock
* ICanHazTehCheezburger

Seriously, I would even look at what my class name was as well. If my class was called "File", I would probably just go with

*UploadToServer
*DownloadFromServer

So it would be

   File file = new file;
   file.UploadtoServer(ServerAddress);

Just a trivial example, but hopefully that's illustrative enough.

share|improve this answer
    
Hehe. I've actually seen "Teh" creep into method names following the "English-like" naming pattern. As for your second point: I completely agree, redundancy in methods names is another pet peeve of mine (File.UploadFileToServer...ugh). –  Mike Spross Sep 16 '10 at 6:24
add comment

I personally don't care. I've seen them and they don't bother me. I didn't even think about them until another programmer went on a rant about them. I found it shocking that somebody would care so much about something that matters so little. I mean he was actually angry about it. But that was early in my career, about 11 years ago, and since then I have found that developers being angry about minor things is actually quite common. It is why managers of developers get paid so well. They have to deal with developers on a daily basis.

And I would rather see that than "UL_FlToSrv".

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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