Style, in any artistic or professional endeavour, is impossible to quantify, define or measure. It’s highly subjective and can often be controversial. So I’m going to push my own opinions in this, the first of several posts on the subject of coding styles. They won’t be complex articles, merely a look at what I think is poorly-written code versus how I believe it would be better presented. There will be no attempt to discuss whether the code in question is inherently “correct”; merely that it looks difficult to read and is hard to maintain. The aim is to turn both of these problems around, thus making the code easy to read and maintain.
In cases where there may be several variants, I will present them, and give a synopsis of how “stylish” I think it is.
Your comments, as always, are very welcome on this topic.
Example 1, SOQL Queries in Apex:
Let’s start with a common code segment whereby a SOQL Query is run and the resultant record set is returned into a list data structure.
List<Custom_Object__c> lstRecords = [select id, field1__c, name, number_field__c from custom_object__c where name like 'Smith%' order by lastname, firstname limit 100];
Figure 1, above, shows how an “undisciplined” programmer might put together a code segment that retrieves a record set from a SOQL query. In an IDE or other editor, this might well appear as a single line and you would have to scroll right to see the full detail.
List<Custom_Object__c> lstRecords = [select id, field1__c, name, number_field__c, an_additional_field__c, and_another__c from custom_object__c where name like 'Smith%' order by lastname, firstname limit 100];
Figure 2, above, would show the result of adding two additional fields to be retrieved by the query. Not very pretty.
List<Custom_Object__c> lstRecords = [ SELECT Id , Field1__c , Name , Number_Field__c FROM Custom_Object__c WHERE Name LIKE 'Smith%' ORDER BY FirstName, LastName LIMIT 100 ];
Figure 3, above, is how I would put this snippet together. I find this more professional-looking, much easier to read and far easier to modify. The following improvements have been made:
- the outer data structure is separated from the inner SOQL statement
- code is indented in a useful way
- keywords are uppercase for readability
- query clauses are split onto separate lines
- fields are also split onto distinct lines and vertically-aligned to enable simple editing
- field names have been retyped with appropriate letters in uppercase
You may not agree with the word “improvement”; please let me know if you don’t, and the all-important reason why.
List<Custom_Object__c> lstRecords = [ SELECT Id , Field1__c , Name , Number_Field__c , An_Additional_Field__c , And_Another__c FROM Custom_Object__c WHERE Name LIKE 'Smith%' ORDER BY FirstName, LastName LIMIT 100 ];
Figure 4, above, shows the result of adding the same two additional fields as in Figure 2. The results speak for themselves.
More code examples to follow soon. Why not follow the blog to get email notification of new posts?
Acronyms used above:
SOQL = Salesforce Object Query Language (a proprietary variant of SQL)
IDE = Integrated Development Environment (e.g. Eclipse, MS Visual Studio, NetBeans, JDeveloper, Xcode, etc.)
January 11, 2013 at 3:08 am
Thanks Alan, was wondering how style applies to coding. But clear to see the advantage now. I often find myself trying to writ clean code, but as the program develops I loose focus on presentation. I always thougt clean code was for others to read. And being a novice, it wasnt a priority. But cool to see it broken down line by line for quick review and easy editing.
January 11, 2013 at 3:27 am
Ahhh just wrote a big message and it asked me to login. Wheres the msg? So login first, if you want to comment.
I used a touch keypad on my phone!
…
Sorry Alan, liked the single ine approach. Makes sense for SQL. Plus one on Google.
Aubrey
January 11, 2013 at 9:31 am
Aubrey, thank you for reading the post and for your comments. I see that you prefer the single-line approach i.e. from Figures 1&2 above – sure; I don’t think there’s any right or wrong here but I’d love to hear your reasoning in case I’m missing something.
Pingback: Force.com: Apex Styleguide, Part 2 « Trapdoor In The Sun
Pingback: Force.com: Apex Styleguide, Part 3 « Trapdoor In The Sun
Pingback: Force.com: Apex Styleguide, Part 4 « Trapdoor In The Sun
January 17, 2013 at 10:00 pm
Love the comma-first style, and separating AND clauses into separate lines — makes it way easier to comment out various fields or AND clauses without breaking the query.
Pingback: Force.com: Apex Styleguide, Part 5 « Trapdoor In The Sun