A Problem With My Coding Methodology That's Driving Me Crazy
Usually, I am quite pleased with my coding methodology. But, lately, I have run into a situation that is just driving me absolutely bananas and I think it might be a sign that I need to drastically change a part of my coding methodology - specifically, my naming conventions. Right now, I have the following rules surrounding my variable naming conventions:
All scopes are uppercase (ex. APPLICATION, REQUEST, THIS, CALLER).
All keys on scopes / structs are uppercase camel-case (ex. Struct.Key). The exception to this is the URL and FORM scopes which follow under-score notation (a carry-over from my pre-ColdFusion days).
All non-scoped keys are camel-case, starting with a notation that affords insight into the data type itself (ex. arrContactrs, strName, intCount).
Whether or not you agree with these particular rules, I think we can all agree that rules are required to create coding consistency. Furthermore, I think we can all agree that code that is not consistent is hard to read, follow, and ultimately, maintain. That said, the rules that I follow have been working well until recently.
When I started to work with more advanced ColdFusion custom tags, specifically with tags that inter-communicate, I've found that my rules have created very inconsistent looking code. For example, if I have a child tag that get's access to its parent tag using this notation:
<cfset objParent = GetBaseTagData( "cf_parent" ) />
... I might easily end up with variable chains that look like this:
objParent.objConfig.Type
... or even worse:
objParent.ATTRIBUTES.Type
This is disgusting and it's driving me crazy. In the first line, we have conflicting naming conventions. In the defining context (parent tag), "objConfig" is the proper notation as it is an un-scoped variable. However, when it is referenced from the child tag, it is a scoped variable, which should dictate that it uses capital camel-case. These two are directly conflicting, and I certainly can't have rules that dictate notation based on context!
The second line is even worse! I have a scope that is now the key of another struct. In one line, I use all three naming conventions chained is a crazy order. I see that line and my stomach gets upset. Coding it actually made me feel dirty.
While this situation makes up only a tiny portion of my coding experience, it is enough to convince me that my rules are bunk. If I can't be consistent with my rules, well then, I don't want those rules. So, what rules do I want?
Ironically, and I'm sure many of you will get a chuckle out of this, it seems that I should be following more "traditional" naming conventions as they seem to cover this kind of situation nicely. For example, using a more standard notation, the above lines would look like this:
parentTag.config.type
... and:
parentTag.attributes.type
What I've done here is removed the Hungarian Notation and reverted back to a headless camel-case format across the board. This is nice because it affords consistency across all areas of code (that I can foresee). I'll probably miss the uppercase SCOPES because they offered excellent visual differentiation; but, in reality, that is not a great rule to begin with because in ColdFusion, there is no true separation between scopes and standard structs: Some objects are scopes; others are specialized scopes (ex. CGI, ARGUMENTS); others are really just structs (ex. THIS is a member of VARIABLES inside CFCs). Plus, when you can arbitrarily add structs to the list of objects that ColdFusion implicitly searches for variable references, the line blurs even more.
I'm not going to change my coding style this very second - I'm gonna let this idea simmer for a bit; but, something clearly needs to be done. That nested ColdFusion custom tag example is disturbing and cannot be allowed to exist. Perhaps this is something that I'll just have to start on my next project so that my existing projects don't become inconsistent.
Want to use code from this post? Check out the license.
Reader Comments
I generally follow the latter convention. I mostly work in Flex/AS3 now, so I basically only use ALL CAPS for Constants and Static variables there. I don't think I've ever used ALL CAPS in CF.
I hate how CF converts Struct keys to CAPS is SOAP requests. for instance, if I create this Struct:
greetings.item01 = "hi";
greetings.item02 = "hello";
and return it from my CFC as
...cfreturn greetings...
the response comes back as:
key = "ITEM01"
value = "hi"
key = "ITEM02
value = "hello"
Annoying to write handlers in my front end with the ALL CAPS properties.
@Eric
I'm pretty sure you can preserve the keys' case by using bracket notation instead of dot notation when assigning them:
greetings['item01'] = "hi"
instead of
greetings.item01 = "hi"
It's always interesting to see people's justification for their naming conventions so thank you for sharing that. I think a lot depends on your background. Mine is mostly C++ / Java so for me UPPERCASE means a constant, CamelCase means a type and headlessCamelCase means a variable. And I've always despised Hungarian notation (although what most people call Hungarian is not what Simonyi had in mind!). I've seen a lot of CF code that uses UPPERCASE and/or CamelCase in ways that seem a bit random to me (CamelCase function names drive me insane - and that's in the main documentation!).
I'll be interested to hear what changes, if any, you decide to make and how you feel about them.
@Eric, @Tony
Using bracket notation will definitely preserve variable case. Found this out when I was getting more into JSON. I would use CF to return JSON data for consumption in javascript and all my variables would turn up IN UPPERCASE. Stumbled across the fact that bracket notation preserves case more or less by accident.
I always thought that Hungarian Notation made a lot of sense from a theory perspective... in the classroom. And I can see it being useful in complex mathematical situations (computing formula results in the code that makes Excel work, for example -- which is where the H.N. idea came from); but in reality I've found that H.N. is just not practical or helpful.
I suppose it helps to know that a variable is an object and not an int (objFoo vs. intBar), so you don't try to multiply them, but I find that proper descriptive names do just as well and are more readable. But I'm not afraid of having somewhat large variable names. I like my code to be somewhat human readable.
I'm also less likely to forget that I need to include the H.N. prefix, so I don't find myself thinking, "crap, I forgot it again!" and having to go back and change code I've written. In short, doing what comes naturally works well, because it means I don't have to go back and change it just for the sake of consistency. I skip the all-caps for scope names thing for the same reason. Not only do I forget it the first time around, but I find it a little jarring when reading. Can you imagine if all proper nouns were uppercase in books? That would drive me insane.
Since I've been doing CF I've been using CamelCase for everything, and it's worked out quite well so far. Uppercasing scopes, for me, doesnt' seem like a big deal since there are only a few key words (and a decent editor should colour or highlight a scope name. VIM does this for CF out of the box, one of the reasons I'm a big fan).
I'll agree with @Adam about descriptive names, I have variable/function names that get quite long, but it's readily apparent from the name what the intention is.
@Eric,
Yeah, the case conversion is definitely a pain. One thing that I've started doing is converting back to the "Expected" case when possible in the translation of AJAX return to AJAX handler. Of course that adds some overhead and can be a HUGE pain with large data sets.
@Sean,
Always to share. I like to think I'm pretty transparent on my blog, if nothing else. At the end of the day, I simply like to be able to explain myself in terms of choices; and, it seems to be that this choice is no longer explainable :) Hence, time to change.
@Adam,
I'm definitely all about the descriptive names. One place that I liked data-type-prefixed names, however was when I have two representations of the exact same data. Take XML for instance - I might have something like this:
<cfset strData = GetSomething() />
<cfset xmlData = XmlParse( strData ) />
Here, strData and xmlData are both the same "data", only in different formats. But, I suppose the same could be gotten with more descriptive naming like:
<cfset rawData = GetSomething() />
<cfset data = XmlParse( rawData ) />
@Ryan,
I am not sure if I ever even needed colors on the scopes. It was just a decision I made a long time ago to make these two types of data very visually different; but, perhaps this is not necessary since the lines of data differentiation are so blurry.
As a suggestion for readable descriptive names where the representation is important, you could also use:
dataAsString = ...
dataAsXml = xmlParse( dataAsString );
I'm not averse to having something in the name that indicates the functional type of the data if that is important or open to interpretation / confusion (which is possible when you have the same data in two formats in the same function) but I think it is more important to maintain readability so the code scans like English language as much as possible.
One criticism I've heard about OOP, for example, is the "fact" that you have to go digging thru dozens of objects to figure out what any one line of code does. That just screams poor naming to me. Properly named variables and functions should let you read the top-level function and immediately grok what the code is doing. If you have to dig into other objects just to figure out what a single call is doing, the object name and/or method name are not descriptive enough. In my opinion.
@Sean,
Yeah, that's a good solution for the naming. I don't think it's a situation that comes up all that much; outside of a method than handles parsing of data, I couldn't really think of anything.
Hi Ben,
Usually I use something along the lines of what you use, with a bit of what Sean mentioned thrown in as well. For me, upper-case means "constant" (because I'm also from a C/C++ background), so I don't do upper-case scope names; I do use a similar prefixing system to yours -- arrUsers, strFirstName, etc.
And I've been in the spot you're in now, when that naming convention "gets in my way". Usually I find this is the case when I'm on a project w/ multiple programmers, that's very OO driven (I still maintain several procedural apps that were written by programmers no longer around).
Sometimes one helps me more than the other. Your mileage sounds like it's about the same as mine. I'm just glad to find someone else that scopes things like I do. :)
@Sean
I like it! I've always done as @Ben mentions, prepending a type when there are 2 different representations of the data (xmlData, jsonData, etc.). But keeping it in a more readable English format fits well with my naming so far. Sometimes it's the simple things you never think of.
@Nolan,
I think I might try experimenting with the new naming in my demo code; then, if I'm happy with it, I'll start applying it in projects.
I also agree with Sean 110%. Working with Flex, ColdFusion and Java together really forces you to "behave" in ColdFusion's typeless environment.
I really like this by the way.
"
dataAsString = ...
dataAsXml = xmlParse( dataAsString );
"
I normally do the same thing Ben mentioned.
"
<cfset rawData = GetSomething() />
<cfset data = XmlParse( rawData ) />
"
I am also a believer in very descriptive yet concise variables and functions. If the function requires 25 letters or more to make sense then, let it be.
getBoyWithBlueShoesAndYellowSocks() (English)
vs
getBoyBlueShoesYellowSocks() (???)
In the past I used to take the short route and paid bitterly for it later on.
Now that I'm doing more development in Flex, I've run into a similar issue, only it's not about capitalization, it's about spacing.
I've seen the same code written a few ways:
[Bindable]
public var foo : String = "bar";
[Bindable] public var foo:String = "bar";
In this case, I'm currently leaning toward the latter, because it seems just as readable to me, while being a little bit more concise, so I can fit more code on-screen.
Then there's:
private function doSomething( arg1 : String , arg2 : Boolean) : void
{
//do something
}
private function doSomething(arg1:String, arg2:Boolean):void{
//do something
}
I have trouble with this one. I like the spacing of the former because it's a little easier on the eyes... it doesn't feel as busy and cluttered. But it wastes a lot of space, and starts to look like every Java class I've ever seen. The minimalist in me wants to write like the latter version, but it can be hard on the eyes at times. I don't know what to do. :(
In flex I do the latter for variables and former for functions also.
private function doSomething( arg1 : String , arg2 : Boolean) : void
{
if(some condition)
{
Do Something
}
}
The above seems much cleaner to me and easier to follow. I don't give a second thought to saving space. Readability comes first in my book, so I suppose I am agreeing with your current way of formatting code. :)
The code above didn't indent properly. just noting.
@Adam, @Hussein,
Yeah, I've always been a fan of keeping the brackets on the same line of the method, but as far as readability goes, this probably is the better way to go:
someMethod()
{
. . . . // more code here.
}
For some reason, though, it's just always rubbed be the wrong way.
For the last few days, I've really been trying to embrace the newer code style; one of the things that has been tripping me up is the naming of local variable being the same as object properties.
For example, I might have an object property:
this.pageIndex
... then, I might have a propery to access that:
getPageIndex: function(){
. . . . return( this.pageIndex );
}
... so far so good. But, then, if I have an internal method that uses the pageIndex property, I might have this:
updatePagination: function(){
. . . . var pageIndex = this.getPageIndex();
}
... now, I have LOCAL variable pageIndex and an instance variable pageIndex. I understand that these values are scoped separately and probably won't collide; BUT, I can't stand the fact that they are the same name.
What's worse is that depending on the instance variable, referring to "pageIndex" might refer to that one if there is no *local* version (due to scope searching). Seems very irksome.
How do I deal with that?
In CF, in that case, I use a var scoped struct named local, and in flex I have been trying using the prefix "fn" for function arguments that match a class property. fnDisplayType will be very similar to class property displayType. I'm not sure how much I like this, but at least it makes it clear where the value is coming from in comparisons.
@Adam, I've been a big fan of the var scoped 'local' struct as well.
@Adam,
Yeah, in CF I would probably also use the LOCAL scope. My example in mind came from Javascript, however, where I still use the "var" keyword.... I wonder why I use var in Javascript and var LOCAL in CF? Funky. I guess because in Javascript, you can var anywhere in the function.
I tend to use "fn" to denote variables containing function definitions (such as callback variables).
@Ben, that begs the question: would you stop using a LOCAL struct if CFML let you declare VAR anywhere?
FWIW, the CFML Advisory Committee will specify VAR can be used anywhere in a function as part of CFML2009 (and some vendors already support this).
I would surely give the local scope the big black boot for VARs anywhere, any day!
@Sean,
Hmmm, good question. No, I don't think so. The reason being that in ColdFusion, when going tag-based, there is no "set" command. For example, when using a query:
<cfquery name="local.contacts">
... there is "set" of Contacts - its implied in the internals of the CFQuery tag. To var properly, I'd have to do:
<cfset var contacts = "" />
<cfquery name="contacts">
... and at that point, we've gotten too ugly for comfort. But, if I were in script mode, then maybe yes.
Well I believe its best to stay consistent. I am working on a CMS so I don't have to worry about coding from scratch... this will assure that if I find one problem in one of my applications I can be assured that the same problem is in all the applications so I can just submit a patch... I don't know if that sounds crazy but hey what can you do...
It looks like CF 9 allows you to declare var anywhere in the function. I still think it's a good coding practice (even in JS) to declare all of your local vars at the top. It just feels right, and it gives you a map of all the local variables. It would be cool to have a shorter syntax in CF like <cfset var myvar1="", myvar2="", myvar3="">
@Brad,
Even more than that, though, CF9 now has an implicit "local" scope. As such, the concept of "var'ing" a variable definitely changes:
<cfset var x = "y" />
... vs:
<cfset local.x = "y" />
(which are actually the same exact thing).
@Ben Nadel,
Sweet! I didn't know that. Just another reason to appreciate the guys at Adobe. They shape CF around how developers are using it, and make it easier/faster for us to do the day to day stuff. Very cool!
Ask ten different programmers and you'll get ten different answers.
Well maybe not quite - four might prefer it this way, three another, two yet another, then that one guy that does it all the same way et al.
But you get the idea.
Furthermore just as in written languages/script (as in books) some read right to left, some the opposite.
Does that make either better then the other based on this alone? I think not.
The point is they are a different preferences, a different convention and nothing else.
Yore blog here is objective and pleasant.
And after years of working with many Ivory tower
college graduates..
Not saying you are in this boat, but I hate looking around on the web and finding these people that claim they are the Gandhi(read guru/expert) of all program languages and I therefore claim this is the supreme way.
They write some highly praised (by unknowing, unthinking people) book with a flock of inexperienced people that follow their every step thinking they've found the new messiah.
If some naming helps your through process, if it helps you remember what you were thinking working solo then who gives a $%@#?
And if it's in a group, then just reach some common ground where you can agree on some sort of conventions that you will generally all use so you have some homogeneous platform.
You say "toMato" I say "ToMato", lets.. errm get along..
@Sirmabus,
Yes, everyone (including myself) has their own way of doing things; as long as I can justify to myself and am happy with the way that I do things, and that I do them consistently, that is all that I care about. The key is stay open-minded and never be afraid to question your own standards if you think they can be improved upon.