Here we have a random incoherent steam of thought, in regard to reading the first few chapters of “Clean UI5” from SAP Press. On the front page is a picture of a leaf, as in “take a leaf out of my book”.

Clean UI5 Book

https://www.sap-press.com/clean-sapui5_5479/

In the beginning was “Clean Code” by Robert Martin, whereby most of the examples were in Java, but the basic principles were timeless. That is, that the clearer the code is, the easier it is to understand, and thus maintain, and thus reduce costs and speed up development time.

Then we had the “Clean ABAP” book, backed up by an online Style Guide on GitHub, and also on GitHub a set of ATC checks you could download and use to analyse the custom code in your system. Lars sort of beat SAP to that with his “Open ABAP checks” on GitHub a few years earlier, but anyway, he likes the Clean ABAP style guide that is on GitHub, and so do I. Not everyone is going to agree with everything, but that is to be expected.

How NOT to a do a Book Review

Sometimes SAP Press gives me a free online copy of a book so I can do a review. In such cases I sort of try to write a book review, but it comes out as nonsense more often than not, a sort of rant about the concepts the book (whatever it may be) is talking about. I don’t know why they keep doing this, I suppose any publicity is good publicity as long as they spell your name right as P.T. Barnum once said. The musical about P.T. Barnum with Hugh Jackman was ten billion times better than the one with Michael Crawford from about 25 years earlier, by the way. I bought the Clean UI5 book myself.

The Clean ABAP book got a lot of grief, but I liked it, it was a bit incoherent, but then so I am, people are going to disagree with a lot of it, but that is the whole point, to get people thinking. Put another way if you say “Do XYZ” to make code cleaner people are going to say, no that is madness you need to do the OPPOSITE to make code cleaner. The point is that suddenly people are thinking about the best way to make ABAP code cleaner when they were not before.

James Joyce

So, what I did, was to read the first two chapters of the book, wrote down all the notes I made, and then pretended I would sort them out later. In real life I will just present the notes in the order that I wrote them, and since I read the pages in sequential order, you would hope the notes would come out logically as a result. The only thing that could prevent that is if the book wandered all over the place at random, like I do in my blogs.

JavaScript Things

You can declare a variable twice (or many times) within a “scope” (that is, within a function or whatever) but only the first one counts. In ABAP you get a hard “that has already been declared” error.

I am getting the feeling that the keyword VAR defines a global variable, no matter where it is declared. That is a bit like in ABAP when you define what you think is a local variable in a PBO/PAI module but in fact it is global.

The LET and CONST statements define local variables, which are even more local than ABAP, because they only exist within a programming block, a loop or some such. Apart from that it is just like ABAP – you cannot access the variable before you declare it. As I have mentioned CONST is a bit like a variable in ABAP. Declaring a variable that way is more like an intention that you don’t want the value to change, but you can change it if you want. The syntax check will tell you that if you are doing naughty things like that use LET instead.

The Style Guide Council

On GitHub there are “style guides” that talk about clean code, and the SAP Press books are expansions on this. At least, I thought that was the idea.

At the start of the UI5 book it seems to be teaching me a lot more about the very basics of JavaScript than the basic JavaScript book I have been reviewing. Whilst that is good in some senses, that seems the wrong way around to me, the basic book should explain the basics, the Clean UI5 book should assume the reader knows the basics and concentrate on readability/maintainability matters.

Sometimes you get two options, and it is not 100% clear which one is the “clean” option. You could have two options one after the other which do the same thing. In my mind the option that looks most like Plain English always wins, the option that looks less like machine code. That is words trump symbols.

Back to JavaScript Basics Again

Template literals – here, when building up a string, you use a &1 type variable as opposed to concatenation. The syntax is of course different between ABAP and JavaScript, but the concept is the same. I wonder if ABAP copied this concept from JavaScript or the other way around. Probably the former.

Promises – I was informed, years ago, that a big thing in JavaScript was “promises” where you could write the code so it looked it was synchronous (which made the code easier to read) but really you could control when it paused to wait for the result of something else.

The first example I saw of this (in this book) made me wonder where the pause was. It turns out the word THEN has a subtly different meaning to IF/THEN. In the case it means wait for something THEN do something else.

The subject moved on to “tag fragments” and my notes were “I don’t understand any of this” probably because I am an idiot.

Spread Syntax – two examples of two different ways to do the same thing with the quote “if you implement the same example using the spread syntax, the code is much easier to read” to which my notes were “Is it? Both examples read like gobbledegook”. There is really a lot to be said for verbose languages like ABAP. Why should someone have to guess that three dots (periods) in a row have a special meaning, as opposed to someone having a sneezing fit and pressing the period key three times by accident?

A little later we have to more examples that look almost exactly the same and the second one has the three dots which “makes the purpose explicit” but I don’t think it does.

Moving onto arrays we now have an example of an iterable object which is NOT an array called ARGUMENTS. Is this the right room for the ARGUMENTS?

In the example this is used in a function with the word ARRAY in its name even though it was just stated this is not an array. I suppose because the result looks like an array? Thank god for internal tables I all I can say.

Lovely Rita, PARAMETER Maid

Now we come to the subject of parameters in function calls (as opposed to method calls of objects). The recommendation is the same as in Clean ABAP which is to limit the number of parameters. The reason given here is that because parameters have no names in the caller, it is easy to forget one, or pass the wrong value in. Which is why I presume in ABAP methods the caller is forced to name the parameters if there is more than one going in or out.

The recommendation in JavaScript seems to be not to have a BOOLEAN parameter, and then the recommendation instantly changes (in the next sentence) to use a meaningful name for the function call, so you know what the BOOLEAN parameter means. The example given is a standard SAP UI5 function into which you pass the value TRUE and there is no way in ten billion years you could guess what that function does, so I think they are saying to wrap the standard SAP function with the obscure name in a function with a meaningful name. I think.

Some SAP functions have Hungarian prefixes to say what type of value you should pass in (this is more important in JavaScript than in ABAP due to the lack of type checking) e.g., V for a string, or M for an object (stands for “member” I imagine). I remember when I first started seeing UI5 code on the official SAP websites (long time back now) and I was vaguely surprised at all the Hungarian Notation.

At long last I am going to say something positive. When calling a function like a message box you can pass in another function as a parameter to be called after an event like ONCLOSE. In some ways this is just like the 1999 function module REUSE_ALV_LIST_DISPLAY where you passed in the name of a FORM routine to be dynamically called but much more explicit.

I am going to change subject for no apparent reason. Possibly because the book has so many authors, it seems to be unsure what it’s purpose is. Sometimes it is explaining the basics of JavaScript, sometimes explain very complex techniques, sometimes explaining how the language has evolved over time, sometimes even talking about Clean Code. All mixed together, seemingly at random. Now, back to JavaScript.

I may have got this wrong, but I think the book is talking about having the view in the MVC model in JavaScript, instead of just the controller. Lots of web programmers like doing just that but I understood that with UI5 the SAP recommendation was to have the view in XML. That enforced the separation of concerns by having the model, view and controller all in different languages.

Frank Sidebottom Effect

It looks like certain types of functions have parameters passed by reference, so the function can alter the passed in object, thus causing side effects. I thought the whole point of a functional language was not to have side effects.

Next, we move onto the subject of regular expressions. I have always thought that regular expressions are no fun, and they are also not very “clean” in that they are written in what to all intents and purposes is a secret code rather than Plain English.

As an aside I had written a note saying “things really need to follow on from one another in a logical manner” by which I meant the book is rambling all over the place. I am guilty of that very crime in my blogs, this very blog being a case in point, bit you would think a book would have a more logical structure.

There is quite a good and long section explaining what “promises” are, why they are good, and how not to use them, and how to use them properly. This is very important given the SAP direction in UI5 is that more that is asynchronous the better, but once again, is the books purpose to explain complex JavaScript concepts, or to assume the reader already is conversant with JavaScript and focus more on making the code clearer?

On page 69 we see the term PARADIGM SHIFT which makes the whole audience do a Mexican Wave.

I have an admission to make. One day I was reading the book mid-afternoon and read the explanation of what the AWAIT keyword does. Four hours later I was on a video call with Lars Petersen, and he showed me some JavaScript code which was peppered with AWAIT statements. He asked me if I understood what that code was doing, and I said “of course” as if I had known all about the concept for years.

In the basic JavaScript book I have been writing about, all the examples are to do with music, in the same way my examples are about monsters, which makes the concepts easier to grasp. Some crazy people use aircraft and flights for examples.

Some examples in the Clean UI5 book are a bit too generic using the good old A, B, C for variables and the DO_SOMETHING names for functions.

Once again in my notes I write “This whole thing is more to do with advanced JavaScript concepts than Clean Code”.

Back to Parameters

It is mentioned that as of JavaScript ES6 you can define default values for incoming parameters. I had written in my notes “Well Done!” because of course I have been used to default values in ABAP for a very long time, starting with function modules. Apparently, the rules for default values in JavaScript are a lot more complicated, so much so the book says you need to read the online documentation to really get your head around the concept. So, that is not really “clean” as “clean” concepts should be easy to understand and the code should do what you expect it to do. That is a JavaScript problem, the book is just pointing it out.

You can only have mandatory parameters in JavaScript if you use TypeScript. There is a corker of an example of how to get around this, which is also an excellent example of passing in a function as a parameter. Remember, you can pass in any function as a parameter, a function that can do anything. In this case the default parameter is a function that throws an error. Unless an actual value is passed in to the parameter then the function that is the default parameter is passed in and executes, throwing an error saying a real parameter needs to be passed in.

Now we move onto classes in JavaScript and the examples talk about Function A and Class A, which are a bit generic to say the least. Come back SFLIGHT, all is forgiven.

Here is a quote “None of the properties and methods of SAPUI5 classes are truly private”.

To get around this you are encouraged to follow some naming conventions which in theory should scare off any other developers from changing your private methods and attributes, if they are familiar with those naming conventions and know what they mean, but I have always found that naming conventions are not substitute for the language actually enforcing rules. A JavaScript person would probably say rules are for losers. As an example, I prefer working in Australia to Germany as there are 95% less rules to follow, and I feel that makes me more productive.

I GET so emotional, baby

As we all know, programmers tend to get very emotional about what outsiders would see as very trivial matters. These range from mild disagreements to chopping up the programmers who disagrees with an axe.

One such area is the use of GETTERS and SETTERS to write and read values from an object instance. Some people say that is the only way to do this, some say it is nonsense. In some standard SAP ABAP classes there are GET and SET methods and they even have a special icon that appears next to them, though if a “customer” like me creates such a method no such icon appears. In any event, sticking with the ABAP example, which of course I am doing in a blog nominally about JavaScript, I have tended to use read-only attributes to simulate GET methods, and use SET methods when the attribute is private. For twenty years I have been waiting for a use case whereby I can say I am using a SET and/or GET because there is extra logic to be executed when reading or writing a value. I have not found just a use case yet, but one day it will come, I am sure.

In UI5 I am informed that the library automatically generates SET and GET functions for each attribute, but I think you can also directly read and write the values as well.

In JQUERY everything goes BONKERS. Youi have one function and if you do not pass an optional parameter then it acts a GET method, but if you pass in a value that same function acts as a SET method. Oh dear, that is a clear violation of the “a method should only do one thing” rule, and a wonderful example of why optional parameters are a Bad Thing.

One interesting thing in JavaScript is you can do some jiggery pokery whereby the define the extra logic in SET and GET functions, and then those functions are automatically called when the code does a direct assignment, or a direct read. That is nice, but I hate black magic code, that is something which is not there when you look at the code but gets executed anyway. Logical Databases in ABAP were like that. I was hoping they would be gone in S/4HANA but I think they are still there which is a pity.

At this point I think the author has changed, because instead of very generic examples with classes and methods called A, B and C, suddenly we have much better really specific examples and use cases. Naturally I far prefer the latter.

I think the pattern (in the text of the book) now has changed to first talking about a feature in JavaScript in general, then how UI5 implements that feature in its own particular way, and then some suggestions on how to write the code in a “clean” way. That pattern seems logical and sensible to me, but not all the book is like that, and in the Clean ABAP book the vast majority of the text is talking about Clean Code.

Patricia the Type Scripter

We now move onto Typescript, which UI5 supports. Indeed, in the example in the hands-on session at ASUG TECHCONNECT 2023 many of the files were written in Typescript.

Incidentally, apropos of nothing, JavaScript has the same concept as the ABAP PRAGMA, that is you can write a comment to disable a warning that the static syntax checker (LINTER) would normally give for a specific area of code.

One point raised is that once you have strong typing, then the IDE suddenly becomes ten billion times better when it comes to code autocompletion e.g., if it knows a variable is typed as certain class then it can suggest method names and the like.

It also looks like there is no “interface” concept in JavaScript (in the SE24 sense of the word) but there is in TypeScript.

I cannot be 100% sure but I think this book is recommending Visual Studio Code to write Typescript files. At ASUG naturally we used the BTP, and SAP BUILD CODE, but that has only just been released and thus was not there when the Clean UI5 book was written.

Annotate, Annotate, Baker Man

Now we come to the concept of “decorators”. You will know this in CDS views by the term “annotation” and indeed in Typescript you invoke a “decorator” by putting an “@” sign at the start, just like with annotations in CDS views.

I think annotations is the better name, because “decorator” makes me think of the “decorator” design pattern, which is a different thing altogether. IT’S A DIFFERENT THING!

I could not help but note that the summary contains the phrase PARADIGM SHIFT which once again makes the audience scream and do a Mexican wave.

OK, I have got to the end of chapter 2, which is not very far at all, really. But I am going to have to leave it there for now, as I have a book to write myself!

Cheersy Cheers

Paul