CFCamp 2012 - Great Coding Guidelines - V1.0

Great Coding Guidelines

A beginner’s guide to write code for next generations
Aurélien Deleusière – CF Camp 2012

 Based in Paris, France
 Software engineer specializing in web technologies,
development, architecture and troubleshooting
 ColdFusion since 1998
 Founder of Aurel&Co
 Involved into the French community
 And, yes, I‟m supporting Railo

Who am I?
©Aurélien Deleusière – CF Camp 2012 Monday October 15th 2012

 Think to the next generations of developers
 Think to yourself when you will have to get back to
your code later
 Think to your colleagues… it‟s your reputation…

Code for next generations

 A working code is not enough…
 …it has to be robust and maintainable

Think to the future

JUST A POINT OF VIEW
Before digging into best practices…


 Both of course!
 But I would prefer a clean code than a fast code
 Use performance mechanisms when possible like
mainly caching
 Always understand what you‟re doing:
 may this array can be huge one day?

Readability or performances?

Mark‟s CFML Myth Busters

ART OF CODING
In good hands,
a few lines of CFML looks like poetry.


 Keep your code as simple as possible
 Use small functions, small files, small number of
arguments, small names…
 …small is beautiful
 Break down complex and large things to simple and
little tasks
 Once it works – and is tested - close your eyes and
be confident

Perfection is attained, not when no more can be
added, but when no more can be removed.
Antoine de Saint Exupéry (1900 – 1944)

Less is more

 Don‟t rush on your keyboard!

Before writing, learn to think.
What one understands, one expresses clearly.
Nicolas Boileau (1636-1711)

Think before doing

 Improve your code each time you get back on it
 « Leave code better than you found it »
 Anticipate: This function could do more…
 Consolidate: I‟ve already seen this somewhere…
 Do not duplicate code!
 But in any case: TEST, TEST and TEST!

Improve again and again

 Truth is always in source code
 Be curious
 Be confident
 Do not hesitate to refactor, the only reason that should
stop you is how difficult it is to test

Other principles

 Don‟t mix a logic across multiple language
 i.e. javascript, CFML and SQL
 Keep the logic in one place

Languages mix

 It‟s not about which guidelines…
 …but have guidelines
 When you go into a code is not yours, enter in
stealth mode, mimic the style in place:
 Make impossible to identify you when others read your
code

Stealth coder

 Tags fit well with views
 Script with business code

 You can only use tags, it‟s your choice.
 You can only use scripts, it‟s your choice…
 …but never do that. Never.

Tags or script?

YOUR CODE HAS TO
TELL A STORY
Make it readable!


 Do or do not but do always the same way:
 to indent your code
 „ or “
 ending slash for unary tags <cfabort />
 spaces <cfset count = 0 />
 void lines
 …

 One style by language is a good choice

Coding style: be constant

 Clear name with meaning
 Boolean should begins with is or has (isBlue)
 About case:
 Only object names should begin with an upper case
 Separate words with an upper case, avoid using the
old fashion “_”
public void function onApplicationStart() {
application.physicalRoot = expandPath("/");
application.env = new model.utils.Env(cgi.server_name);
application.sanitizer = new model.utils.Sanitizer();
application.cfTags = new model.utils.CFTags();
application.debug = false;
...
}

Naming conventions

 Don‟t leave garbage into your code
<cfif 1 EQ 2>
...
</cfif>

 Don‟t comment code, remove it

 You identify a portion to improve?
use Eclipse tasks:
//TODO: This block needs to be refactored

Keep your code clean

 Do not overload your code with useless comment

<cfset count = 0 />

 A comment is stronger when it is useful and frugal
application.proxy = {
server = "",
port = 80, // *MUST* be a number
user = "",
password = "”
};

Comments

 Avoid McDonald‟s programming
// =======================================================
// controllo esistenza fornitore su anagrafica
q_fornitore = cfc_fornitori.GetAnagFornitore(idSocieta =
my_idsocieta, idAnag = codFornitore, const = glb.const, dbprop = glb.dbprop);
// =======================================================

// inserimento link fornitore
linkfornitore = structNew();
linkfornitore.idSocieta = my_idsocieta;

//=======================================================
if (q_fornitore.recordcount eq 0) {
// inseriemnto tan030anagfornitori
fornitore = structNew();
.....
// =======================================================

Comments

 Use every scope explicitly. Always
 Arguments, caller, query name, etc.

public Token function init(token) {
variables.token = arguments.token;
return this;
}

Variables scopping

 Declare a variable where it‟s used… avoid the old fashion of all
the declaration on top (legacy from var scoping up to CF8)
public string function generate() {
var i = 0;
var token = "";
for (; i <= 32 ; i++)
token &= chr(randRange(65, 90));

return hash(token, "MD5");
}

public string function generate2() {
var token = "";
for (var i = 0 ; i <= 32 ; i++) {
token &= chr(randRange(65, 90));
}

return hash(token, "MD5");
}

Variables declaration

 Don‟t use Magic Numbers. Never.

<cfswitch expression="#quoteRow.groupID#">
<cfcase value="12">
<cfset quoteRow['isAnnual'][1] = "yes" />
</cfcase>
<cfcase value="13">
</cfcase>
<cfcase value="24">
</cfcase>
<cfcase value="25">
<cfset quoteRow['isAnnual'][1] = "no" />
</cfcase>
</cfswitch>

Variables usage

 Don‟t use the pound sign where it is not needed
<cfset newColor = #oldColor# />
<cfset newColor = "#oldColor#" />

 But do instead:
<cfset newColor = oldColor />

Variables usage

if (isBlue == false) {
...
}

Prefer:
if (!isBlue) {
...
}

Logic

if (!isBlue) {
doThis();
} else {
doThat();
}

Prefer avoiding “if not else”:
if (isBlue) {
doThat();
} else {
doThis();
}

Logic

if (isBlue) {
return true;
} else {
return false;
}

Prefer:
return isBlue;

Logic

 Parenthesis:
if (isBlue || isRed && isSquare) {...}
if (isBlue || (isRed && isSquare)) {...}

return variables.token == arguments.token;
return (variables.token == arguments.token);

 Order of variables
if ("blue" == color) { //don‟t, use EQ?
...
}

Logic

if (token.equals("1234"))
writeOutput("ok");
else
writeOutput("ko");

Prefer:
if (token.equals("1234")) {
writeOutput("ok");
} else {
writeOutput("ko");
}

Always use brackets

 Exceptions allow you to focus on the useful code
<cffunction name="login" access="public" returnType="boolean" output="false">
<cfargument name="username" type="string" required="yes" />
<cfargument name="hash" type="string" required="yes" />

<cfscript>
try {
var user = request.object.new("User").init(arguments.username);
var hashServer = hash(session.token & user.getPassword(), "MD5");

if (hashServer == arguments.hash) { //connection success
session.user = user;
user.lastLogon(username);
return true;
}

var debug = "username=#user.getUsername()#<br>password=#user.getPassword()#<br>";
} catch (objectNotExistsException e) {
var debug = "user not exists exception (#arguments.username#/#arguments.hash#)";
} catch (connectionFailedException e) {
var debug = e.message & "<br>" & e.detail;
}
</cfscript>

<cfthrow type="loginFailedException” message="...” detail="#debug#" />
</cffunction>

Exceptions

 Don‟t make entities dependent on each others

<cfset colors = "blue,red,green,yellow" />
<cfloop from="1" to="10" index="i">
<cfinclude template="sometemplate.cfm">
</cfloop>


<cfset i = 0>
<cfloop list="#colors#" index="lst">
<cfset i++ />
...
</cfloop>

Decoupling

Principle: no dynamic value into the condition of a loop

for (i = 1 ; i <= arrayLen(items) ; i++) {
...
}

About readability

len = arrayLen(items);
for (i = 1 ; i <= len ; i++) {
...
}

Improvement: 0% to 5%

About readability

for (item in items) { // Railo and CF since 9.0.1
...
}

Improvement: 10% to 15%

About readability

A REAL WORLD
EXAMPLE
We learn more from our mistakes


 Control birth date:
 60 days minimum
 Must be right with the age entered (previous screen)

Requirements


if (tmp.length == 3) {
var year = tmp[2];
var day = tmp[0];
if (isValidDate(month,day,year) != true) {
return false;

} else {
return true;
}
}

return false;
}

Rewriting step 1


var year = tmp[0];
var day = tmp[2];

return isValidDate(month,day,year);
}

return false;
}

Rewriting step 2

function isBirthDateValid(value, element) {

var day = tmp[0];
var month = tmp[1] - 1; //month start at 0
var year = tmp[2];

return isValidDate(month, day, year);
}

return false;
}

Rewriting step 3

Date.prototype.getAge = function() {
var today = new Date();
var age = today.getFullYear() - this.getFullYear();
var monthes = today.getMonth() - this.getMonth();
var days = today.getDate() - this.getDate();

if (month < 0 || (monthes == 0 && days < 0)) {
return age - 1;
} else {
return age;
}
};

Date.prototype.getAgeInDays = function() {
var today = new Date();
return Math.floor((today - this) / 86400000); //ms to days (24*60*60*1000)
};

Final code

Thank you! Vielen Dank! Merci !
@adeleusiere • aurelien.deleusiere.fr • cfml-france.com

CFCamp 2012 - Great Coding Guidelines - V1.0

Recommended

Recommended

More Related Content

Similar to CFCamp 2012 - Great Coding Guidelines - V1.0

Similar to CFCamp 2012 - Great Coding Guidelines - V1.0 (20)

Recently uploaded

Recently uploaded (20)

CFCamp 2012 - Great Coding Guidelines - V1.0