Programming

Clean Code Conventions for SAPUI5

Previously, I explored the need for clean code, test-driven development, and static code checks when producing SAPUI5 applications.

 

Using clean code is important because it makes the application easier to understand, change, and extend. Agile applications like that better support SAP customers’ business objectives. Clean code supports our goal of quickly creating robust, quality code.

 

So, the natural questions to ask are: “what does clean code look like?” and “how does clean code improve quality?” To better illustrate what clean code looks like and how it can benefit a developer, this post will examine some “normal” code and compare that to a clean version. In the process, we can explore how this benefits the developer.

 

General Naming Principles

To start, choose meaningful names. Meaningful names are what makes code self-documenting. Remember, most of a developer’s time is spent reading other people’s code (or reading your own after a long hiatus), so being able to quickly and accurately determine the purpose of the variable or function is key. In other words, the code should roughly be something like an English (or other language) description of the purpose.

 

Variable Names

We start with what I call “thoughtless names.” Everyone has the experience reading (or writing!) code that has variable names like “i” or “j” for an integer value, or “a” for an array, like that below.

 

sum: function(a) {

 

for (i=0;i++;i<a.length) {

               tmp = t + a[i];

}

return tmp;

}

 

No doubt the original developer thought it would “save typing” by using single letter variables, and a short (but ambiguous) function name. Every serious IDE has auto-complete functionality now, so there really is no good reason to abbreviate like that. Seriously.

 

In the early 1990’s Hungarian notation became popular because of the increasing use of Microsoft programming environments and libraries. In Hungarian notation, a variable name starts with a group of lower-case letters which are mnemonics for the type or purpose of that variable, followed by whatever name the programmer has chosen; this last part is sometimes distinguished as the “given name.”

 

Our example above might read more like this when using Hungarian notation:

 

sumOfValues: function(aValues) {

 

for (iIndex=0;i++;iIndex<aValues.length) {

               iTotal = iTotal + aValues[i];

}

return iTotal;

}

 

While this seems better, and implicitly gives us more insight, knowing the type doesn’t give us insight into the purpose. Further, auto-complete will likely require more letters to identify a specific variable given that all of the variables of a particular type start with the same prefix. And lastly, Hungarian notation can be confusing when used to represent multiple properties.

 

Using a clean code approach, our code could look more like the following:

 

sumOfTotalProfit: function(monthlyProfits) {

 

monthlyProfits.forEach(month) {

               totalProfits = totalProfits + montlyProfits[month]

}

return totalProfit;

}

 

The combination of these variable names certainly makes our code read more like an English language description of our intent. A concise, easy to read summary of clean code naming conventions, that expands on the basic concepts introduced here, can be found in this Medium post.

 

Functions

In the second part of this post, we’ll examine how to make functions clean. Clean functions have two readily identifiable characteristics. They are:

  1. Small in size.
  2. Based around the single responsibility principle (SRP) of “do one thing and one thing only.”

We submit that small, SRP-compliant functions, are more readable. To be small, the function should be between 4 and 20 lines. If it is more than 20 lines, you probably can extract a couple of lines into a new method. So, instead of having a giant block of code, reduce that function to one that runs several smaller functions.

 

Robert Martin’s book Clean Code: A Handbook of Agile Software Craftsmanship includes a well-known example (in Chapter 3, “Functions”) of this important idea of “deconstruction.” To summarize, Martin shows how more than 60 lines of code in single function could be re-written:

 

renderPageWithSetupAndTeardowns: function(PageData, pageData, boolean isSuite) {


var isTestPage = pageData.hasAttribute("Test");
if (isTestPage) {

var testPage = pageData.getWikiPage();
var newPageContent = new StringBuffer();
includeSetupPages(testPage, newPageContent, isSuite);
newPageContent.append(pageData.getContent());
includeTeardownPages(testPage, newPageContent, isSuite);
pageData.setContent(newPageContent.toString())

}

 

return pageData.getHtml();

}

 

Of course, a function would need to be written for each of the lines contained in this function. The benefits to the developer are many: if the function is small, it will be easier to isolate any logic error during testing, and it will be much easier to determine the purpose of the function.

 

Conclusion

To summarize, our SAPUI5 clean code conventions include using meaningful (and pronounceable) names, creating functions that are small, and are SRP-compliant. There are more, but refactoring code to achieve even these two standards can leave a marked improvement in readability.

Recommendation

Testing SAPUI5 Applications
Testing SAPUI5 Applications

Take a deep dive into application testing for SAPUI5! Learn how to use QUnit for unit testing and build one-page acceptance tests (OPA) for your components. Isolate and remove dependencies from your code using backend mocking. Round off your education with a start-to-finish example that will show you the ropes!

Learn More
Ian McCallum
by Ian McCallum

Ian McCallum is an executive advisor for project success at SAP America. He has worked as a solution engineer and architect at SAP and led several SAP projects in participation with SAP partners.

Comments