The question, Stored procedure Naming conventions?, and Joel’s excellent Making Wrong Code Look Wrong article come closest to addressing my question, but I’m looking for a more general set of criteria to use in deciding how to name modules containing code (classes, objects, methods, functions, widgets, or whatever).
English (my only human language) is structured as action-object (i.e closeFile, openFile, saveFile) and since almost all computer languages are based on English, this is the most common convention.
However, in trying to keep related code close together and still be able to find things, I’ve found object-action (i.e. fileClose, fileOpen, fileSave) to be very attractive. Quite a number of non-English human languages follow this structure as well.
I doubt that one form is universally superior, but when should each be used in the pursuit of helping to make sure bad code looks bad?
2
actionObject sounds like a method you’d use in order do to some action with/in the object.
objectAction sounds like an aggregate of information, about the execution/result of the action performed on a object.
So I would generalize and say:
- actionObject is appropriate for methods
- objectAction, about information aggregation, like simple classes and structs.
One example of that would be:
- ReportSecurityFlaw: seems like a method to inform a security flaw
- SecurityFlawReport: seems like an object that represents data extracted from already stored Security Flaws
2
related code close together and still be able to find things
thats what packages are for. The difference between fileSave or saveFile is insignificant.
You should consider the importance of the entities involved in the function you’re describing, and apply a naming convention based on that – probably by naming the most-important-first. I’ll try to clarify with some examples.
The object-oriented paradigm considers “objects” to be the most important entities you work with, and you’ll find that objects just about always come first when defining behaviors. If you are calling an instance method of an object, then the instance is named before the method is named (File f; ... f.close(); – f precedes close();). If you are calling a class method, then the class is named before the method (File::open(fileName) – File precedes open(fileName)).
On the other hand, in a more algebraic paradigm, you might consider operations to be more important than the objects against which they operate. If I want to add two integers (ignoring the possible existance of a + operator), I’d prefer to name the operation addIntegers, rather than integersAdd(), because it’s more important to me that I’m performing an addition than that the numbers involved happen to be integers.
To get back to your example – which part of openFile would you consider more important? The open, describing the operation, or the File, defining the domain in which the operation applies? (bearing in mind NimChimpsky’s point that packages already solve the issue of grouping related code together) I’d think that open is more conceptually important than that you’re dealing with files (for example, the calling code might decide to open a socket instead of a file, which may have no noticeable effect on the rest of the calling code), so it should probably come first in the function name.
Real World – Go with Object-Action
I worked in a small shop that created and hosted 600+ websites. We amassed a huge code library and when you are looking for a comlpete code set that you can borrow from one site and plug into another site it doesn’t take very long to determine that the Object-Action namining convention works best.
- Who’s got the PressRelease-XXXXXXX widget? (code and sql scripts)
- Which PhotoGallery-XXXXXXX do I need?
This naming convention makes stuff easy to find, package, deploy and debug.
0