Code Indentation

  
Up until the day that I joined OutSystems, I was developing in written languages, as in not visual: AKA “the old way”. I always took care of the way that I indent my code, either for my own readability or for others, but it was always something that I was very proud on keeping a sharp eye on. The IDE should be no less than a canvas is for a painter! Be proud on what you do, it is also craft and it is no less than any other one!
 
More than making you think on being an OutSystems Picasso, I want to reflect on why we should have an indentation standard for OutSystems.
 
First of all let’s look at the benefits:
·         Using a common practices to layout actions creates visual standards that are easily followed and understood by others;
 
·         It conveys intention;
 
·         Makes code easier to read;
 
·         It is a main factor to augment code maintainability;
 
·          It is a main factor do augment code changeability;
 
And you may now be asking if there’s any downside to it. Of course there is. And the one that I think it matters the most is the time you spend on trying to indent the code. The best solution for this is to use common sense I would say….
 
Let’s start with a really bad example… if you have an action like the following… you still have a problem… and there’s no code indentation that will save you…
 

Go and refactor!
 
Since I find it very important, I’m doing my own suggestion of code indentation to the community. Short notice: all of these are based on teachings by João Quitério J
 
Action Start

By default an action starts like you see in the previous picture. In my opinion that’s a lot of unused space in the left. So I always start my actions like the following:
 

I press the left cursor 13 times (yes you can call me crazy) and the first node starts to the left. My feeling is that the start element is actually pointing to the start of the action and it is not the actual start… After the first node, all actions are laid on the canvas pointing down, so that the reading is easier.
 
Spacing
Real-estate is not cheap. When you buy a house, and when you design logic in service studio. Land is expensive because they’re not making any more these days, and Service Studio real-estate is expensive because you have to scroll a lot if you don’t keep a good spacing. So, in my actions, I always try to follow the following rules that I’ll try to capture in images…

This is a nicely layout action. You can see that the spacing between elements it’s the same and it is sufficient to give some white space in between elements, facilitating reading and understanding. If the description grows, you have to push the elements down to get a nice layout on your actions, like this:
 

 

If statements
What about if? (First time in history that this statement makes sense!)

When you need an if, the inner statement of the if should be laid to the right, and they should be the exception to the normal flow of the action. Keep the labels “True” and “False” always visible.
 

For Each
In a foreach, I always have a clockwise flow, like the following image. This is one that really helps to take a standard approach so that you can read others code easily.

 

And for now it’s all!

Can you guys share your thoughts on these?


Oh, and by the way....




Cheers!
Thank you Pedro, for sharing this!
Pleasure, hope you enjoy it!
Thanks for sharing.
I don't like the indentation of the For Each.
To select the flow bellow an element, If you use shift+ctrl+left click on the for each element, the elements inside the cycle don't get selected. Do you have a suggestion for this?
Tiago Bernardo wrote:
Thanks for sharing.
I don't like the indentation of the For Each.
To select the flow bellow an element, If you use shift+ctrl+left click on the for each element, the elements inside the cycle don't get selected. Do you have a suggestion for this?
 
Hi Bernardo, you're right! Never noticed it.

You could have your foreach layout out like this:



So clicking on the foreach selects all the descendants, or you can make it look like the one you didn't like, and click on the first node to select all contents, with ctrl + shift + left click. In this case however, if your first node is not the one that is closer to the top, the rest don't get select. Thinking on this, I say that I would rather use the one I just posted :)

Thanks for noticing it!

 
I have my own personal standards for code layout... problem is, for the functions complicated enough where it will make a difference, they will completely break the standard. Try a switch statement with 10+ conditions in the middle of a loop if you do not believe me...

What've found is that keeping the right amount of space between nodes, and being rather consistent with how you handle the true/false outputs of an if (I like to always have "true" below and "false" to the right, since that is the "exception to the rule") are the most important things... and trying my best to use If widgets instead of if expressions in Assigns to make it more clear where the decisions are being made.

J.Ja
Hi Justin

I get what you're saying. in some cases I've solver switches likes that by having two switches connected. The first handles four conditions and the "otherwise" goes to the second switch that handles the other 5...

Cheers
We can go even further and make it impossible to creating bad code layouts! :)
http://drakon-editor.sourceforge.net/language.html
(skim through the first slideshare presentation)
Davide Marquês wrote:
We can go even further and make it impossible to creating bad code layouts! :)
http://drakon-editor.sourceforge.net/language.html
(skim through the first slideshare presentation)
 
I Like it :)

 
Thank you Pedro Cardoso for starting this thread, just hope newcomers see it!

Thanks Davide for the cool presentation, it will come in handy when I need to train someone in Outsystems! ;)

And I'm glad to see that I'm compliant with those rules, exception made for the "only one end" thats a really tough one to follow in complex actions with multiple possible outcomes. :/
Hermínio Mira wrote:
Thank you Pedro Cardoso for starting this thread, just hope newcomers see it!

Thanks Davide for the cool presentation, it will come in handy when I need to train someone in Outsystems! ;)

And I'm glad to see that I'm compliant with those rules, exception made for the "only one end" thats a really tough one to follow in complex actions with multiple possible outcomes. :/
 
 Hi Hermínio

I don't like that only one end also.