I’m a cranky programmer. I’m old and approaching curmudgeon status when it comes to code. I fully expect my colleagues to eventually lock me in a back room somewhere to wait for the mysterious “double flash.” I don’t know how I got here, but I’m here now and I know that I MUCH prefer readable code. Like it or not, there’s a very good chance that someday you’ll have to “open the kimono” and allow other developers to read, and even *gulp* modify code you’ve written. As a consultant, I’ve come into some code that is very easy to read, as well as come into some code that is next to impossible to decipher. Don’t get me wrong, I’m very certain I’ve written some code that has been hard to decipher and probably still do. However, one thing I learned when writing Python code in my previous life was that explicit can be a beautiful thing. Although its entirely focused on Python, a read-through of PEP-8 can do wonders for your code’s readability by getting you to think about a consistent style. I’ve not seen a coding “style guide” from the Apex world (I’ve found this and hope it gains some ground. I haven’t had a chance to consume it all yet, but its a start). That being said, the point of this is not to get into the specifics of a particular language but rather points to ponder in a hopefully “language agnostic” manner.
- Method Names: Luckily I’ve not seen the proliferation of bad method names lately that I used to see. However, I like to try to avoid un-necessary abbreviations. Be explicit and tell me what that method does. Such as “UpdateOpportunityStage” rather than “updateStage” — this is a very bad example in that if I’m working in a file like “OpportunityExtension” a method called “UpdateStage” should be obvious, however as an outsider coming into your org, how am I to know if you’re not updating some related object’s custom field stage? For just a few more keystrokes, you can have valuable clarity.
- Variable Names: more important, in my mind anyway, are the variable names that you use. Avoid abbreviations here like the plague as well. You’re not saving yourself much in the grand scheme of things, and to an outsider trying to learn the ins and outs of your code (and your business) an abbreviation can be a head-scratcher. For instance, if you have a product called Extra Widgets and you need to work with one in your code, call the variable extraWidget, not “ew” or exWg, etc. There are times when an abbreviation makes sense however, such as when everyone, and I mean everyone, refers to Extra Widgets as “EWs”, then perhaps saying “ew” is fine. However, if I’m in a rather large class file and that variable is instantiated way above the fold somewhere and I run across “ew” — wouldn’t it be a bit clearer if instead of having to figure out what “ew” was, its name told me right away: extraWidget. Again, clarity gets the nod.
- Spacing: Python introduced me to something that developers either love or hate. The used of whitespace. In Python, it can get annoying for newbies because indented code signifies your “blocks” — there aren’t curly braces or semi colons. This results in very readable code. It does however mean that many a new Python developer runs into issues at “compile time” because they used a tab in one place and 4 spaces in another. (Don’t get me started on the whole tabs vs. spaces thing…). I love white space and I tend to use insert carriage returns before I introduce larger chunks of logic flow. It separates your code into readable chunks of logic. Like Java, Apex is littered with curly braces and semi-colons galore, punctation that the mind just isn’t used to reading “naturally” — by adding whitespace between the different blocks of logic provides a natural separation and seems easier on the eyes.
- Comments: Its been said that good code comments itself, and while this is indeed true it doesn’t get you out of commenting code. I believe the real problem here however is the content of those comments. Of course good code comments itself, but it doesn’t tell you WHY its there or performing its duties in the given manner. It doesn’t tell you what was in the programmers head at the time it was written. Good code comments tell you WHY something was done, not necessarily WHAT it was doing. These types of comments can prove very valuable to any new programmers inheriting your code, or even to yourself when you have to revisit code you wrote months and sometimes even years ago. We’ve all had that moment when reviewing old code where we’ve said: “What the HELL was I thinking, why did I do it like THAT?” only to begin charging down the refactor path until you stumble across that little business rule you forgot about and realize: “Oh, THAT’s why I did it that way!” #BeenThereDoneThat
- Coding Shortcuts: I imagine I will catch proverbial hell from some folks on this and its really a matter of opinion (as all of this post is) but hear me out. Code “shortcuts” (like ternary operators) have their place in “oh-look-how-few-lines-of-code-I-took-to-write-this land, but they do NOTHING for readability for me. We’ve all seen them and I’d like to think I’m not the only one that sort of has to blink their eyes and read them twice:
SomeVar var = (x == true) ? thisVar : thatVar;
I can appreciate its simplicity and concise presentation, but I still prefer to read this:
SomeVar var; if(x == true) { var = thisVar; } else { var = thatVar; }While this is quite a few more lines of code its VERY clear to a newbie programmer (or cranky old one) under which conditions the value of “var” will be set to either “thisVar” or “thatVar” Most programmers are used to reading the ternary so it’s not a huge deal, but I know for myself, I always have to re-read those conditions twice to be sure. These are somewhat similar to the whole “one liner if statement” where if you are only checking if a given condition is true, you can do so on one line and eliminate your curly braces etc. (It figures, the one time you can actually NOT use the curly braces, and I don’t prefer it…weird).
In closing — I’m set in my ways and wouldn’t expect anyone to conform to how *I* want things done. However, diva though I may be — I hope that some of these points would cause one to ponder, if only briefly, about the readability of ones code by outside sources. It won’t always be a seasoned vet, or someone who knows your business in and out that winds up reading your code. They’ll have enough to deal with coming up to speed on the ins, outs, and whys of your business, learning the local vernacular, etc. Therefore, making your code a little more legible can remove one less barrier to entry. And with that, its back in the closet I go.
:wq!