views:

374

answers:

12

as you can probably tell from my previous posts i have horrific naming conventions. do you know of any tutorials dealing with how to name stuff?

+3  A: 

Not a tutorial... more like a guide/best practice kind of thing:
http://msdn.microsoft.com/en-us/library/xzf533w0(VS.71).aspx

Thiago Santos
additionally http://weblogs.asp.net/scottdockendorf/archive/2005/01/26/361020.aspx
drachenstern
+3  A: 

I'd recommend purchasing a copy of "Clean Code" by Robert C. Martin. It is full of great suggstions ranging from naming conventions to how to write easy-to-understand functions and much more. Definitely worth a read. I know it influenced my coding style since reading it.

Mike H.
+1 Clean Code has definitely changed the way I code.
Aaron Daniels
+3  A: 

hi for me you should always put the most explicit names:

string_to_hash = "blabla"
hash(sring_to_hash)

and respect the pep8 style guide. You code should then be very easy to read.

Mermoz
+11  A: 

i will recommend to check this book alt text http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=sr_1_1?s=books&ie=UTF8&qid=1281129036&sr=1-1

Amr ElGarhy
beat me to it!!! (also: start around page 280 for the variable naming stuff, he gets to it pretty early on)
drachenstern
+2  A: 

You didn't specify what language are you looking for. Since your question is flagged .NET, here is a document I follow when writing C# code: http://weblogs.asp.net/lhunt/pages/CSharp-Coding-Standards-document.aspx.

Necros
+2  A: 

Have you read Code Complete? He does a full treatise on this in the book. Definitely the best naming strategy I've seen in print... And it's easy to find like 1000 programmers at the drop of a hat who name this one of the top 5 resources for programmers and program design.

Just my $.05

drachenstern
+3  A: 

There are many different views on the specifics of naming conventions, but the overall gist could be summed up as:

Each variable name should be relevant to whatever data is stored in the variable.

Your naming scheme should be consistent.

So a major no-no would be single letter variables (some people use i and j for indexing loops, which is OK because every programmer knows what they are. Nevertheless, I prefer 'idx' instead of 'i'). Also out are names like 'method1', it means nothing - it should indicate what the variable holds.

Another (less common) convention is the 'Hungarian' notation where the data type is prefixed to the variable name such as 'int i_idx'. This is quite useless in modern, object oriented programming languages. Not to mention a blatant violation of the DRY principle.

The second point, consistency, is just as important. camelCase, UpperCamelCase, whatever - just don't switch between them for no reason.

You'll find that naming conventions vary from language to language and often, a company will have their own rules on naming.

Its a worthwhile investment to properly name your variables because when you come to maintain your code much later on and you have forgotten what everything means, it will pay dividends.

rmx
As somebody else pointed out, the 'Hungarian notation' you point out here is not the (useful) practice originally conceived -- look for Systems vs Apps. Wikipedia even has a full section devoted to it.
Peter Leppert
+7  A: 

I don't think there will be any good tutorials, because there aren't any hard-and-fast rules. Here are some tips:

  • Conform to convention: Loop variables are i, j, and k; variable numbers of arguments go in *args and **kwargs; use camelCase or underscored_names.

  • Be consistent.

  • Be concise. list_of_drugs_used_in_this_program is much less clear than drugs. Similarly, you don't need to include the datatype of the variable in the name: drugs_list is redundant.

  • Don't go overboard with the underscores. I've never needed more than one. 2+ is pushing it.

  • Never ever ever use metasyntactic variables (foo, spam...) in anything but quick-and-dirty examples. method1 is also out.

But you could summarise all of that with:

Don't be silly.


Tee hee.

Variable naming conventions can often turn into a religious war, but I’m entirely confident when I declare The World’s Worst Variable Name to be:

$data

Of course it’s data! That’s what variables contain! That’s all they ever can contain. It’s like you’re packing up your belongings to move to a new house, and on the side of the box you write, in big black marker, “matter.”

http://www.oreillynet.com/onlamp/blog/2004/03/the_worlds_two_worst_variable.html

katrielalex
$data is a perfectly good name for a general-purpose data-handling routine that doesn't know or care what the nature of the data is. It's like what's a poignant love-letter or an angry arrears-notice to you are both just mail to the mail carrier.
Jon Hanna
+4  A: 

All the answers here are quite valid. Most important: be consistent.

That said, here are my rules (C#):

  • camelCase identifiers -- I personally find this much easier to read than underscores
  • Public properties start with a capital letter
  • Something I should never touch starts with an underscore -- example, the backing field to a property should only be touched from the property. If I have underscores elsewhere, I know I'm wrong
  • Apps Hungarian where appropriate -- ints describing row IDs perhaps could be named rowSelected, rowNextUnread, et cetera. This is different than Systems Hungarian, which would mark them as ints such as iSelected, iNextUnread. Systems Hungarian doesn't add much if anything, where Apps Hungarian gives information the type doesn't: it tells me adding rowItemsPerPage and colSelected is a meaningless operation, even though it compiles just fine.
Peter Leppert
Well, there could be a reason for adding rows and cols, but yes, having the intent presented in the logic makes checking against documentation (or heaven forbid, creating documentation) much much easier. Thank you @Peter Leppert, for encapsulating the rules into something tiny and compact. `hehehe, I still suggest he go read Code Complete, but that's only 'cos it's the answer I gave ;)`
drachenstern
"camelCaseEverythingIPersonallyFindThisMuchEasierToReadThanUnderscores." camel case everything? seriously?
Inverse
I thought the brevity of "everything" would be better than the more technically correct "variable names, method names, class names, namespaces, and any other identifiers" -- I never thought somebody would take it to mean "Full sentences". I meant places where people tend to use underscores or justmashingeverythingtogether. Sorry for being so unclear.
Peter Leppert
@Peter, I find that using 'da kine' is much clearer than 'everything'in such situations http://en.wikipedia.org/wiki/Da_kine
aaronasterling
+4  A: 
  1. A bad convention followed fully is better than a combination of different good "conventions" (which aren't conventions at all any more, if they aren't kept to).
  2. However, a convention that is making something less clear than if it had been ignored, should be ignored.

Those are the only two I would state as any sort of rule. Beyond that convention preferences are a matter of opinions quickly turning into rants. The rest of this post is exactly that, and shouldn't be read as anything else.

  1. For collections, use natural language plurals. In English, this means data, schemata, children, indices, criteria, formulae (and indeed foci, geese, feet, men, women, teeth) not made-up words like datums schemas, childs, indexes, criterions, formulas (and likewise focuses, gooses, foots, mans, womans, tooths, believe it or not I've actually seen some of those in use). Camel-casing and abbreviatiating does enough damage to English as it is, without doing more. Okay, I've never seen datums, but I have seen the meta-plural datas. Sweet Aradia, why?
  2. That said, use American English for names, even if you use a different dialect of English. Most coders with such dialects have learnt to think of "color" as a word for colours in a computer context by the age of 12, and the principle applies more widely. If we can deal with "color" (one of Webster's worse bastardisations) we can deal with -ize and -ization (-ise and -isation is a pseudo-French 18th C affectation anyway, the Americans are the traditionalists on this one).
  3. Similarly, if you aren't sure how to spell a word that you are using as the whole or part of a name, look it up (google it and see what google says). Somebody may spend a long time distracted by your misspelling that is so liberally distributed throughout running code as to make fixing it daunting.
  4. Hungarian is bad (in many modern languages, though in some it has its place) but the principle is good. If you can tell a const, static, instance, local and parameter variable from each other in a split-second, that's good. If you can tell something of the intent immediately, that's good too.
  5. Related to that, _ before public variables makes them non CLR compiant. That's actually a good thing for private variables (if you make them public for a quick experiment, and forget to fix the visibility, the compiler will warn you).
  6. Remember Postel's Law, "be conservative in what you do, be liberal in what you accept from others". One example of this is to act as if you are using a case-sensitive langauge, even if you're using a case-insensitive one. A related one is to be more of a stickler in public names than private ones. Yet another is to pay more attention to following conventions well than to complaining about those who don't.
Jon Hanna
+1  A: 

Can I make a shameless plug for the "Names" chapter in my book, "A Sane Approach to Database Design" ? I'm specifically talking about names for things in databases, but most of the same considerations apply to variables in programs.

Jay
+1  A: 

It's not clear if your question relates to Python naming conventions.

If so, for starters I would try to follow just these simple rules:

  • ClassName - upper case for class names
  • variable_name - lower case and underscore for variables (I try to keep them at two words maximum)
Rui Vieira