A code style guide for OutSystems (2022)

A code style guide for OutSystems (1)

Java, C#, JavaScript, and many other programming languages, have established style guides. As a professional, you learn how to style your code according to those industry standards, and you can even evaluate someone’s skills by their familiarity and adherence to coding style guides.

OutSystems, however, is lacking its own established style guide. I believe that is mostly because OutSystems is radically different than any other programming language you have seen, and “code” is designed visually on a 2D canvas. OutSystems developers can freely choose, on their own, how to layout their code: vertically, horizontally, diagonally, in star patterns, in the shape of a butterfly… I’ve seen them all! They all work the same, but which one looks better?

Code is language. Like any language, there’s a writer, and there are a potentially large number of readers. The burden of clarity lies with the writer, and the burden of attention lies with the reader.

A great coding style is one that increases the clarity of the code, and reduces the burden on readers. It will, of course, increase the burden on the writer, but that pays off very quickly.

There are 3 principles for a great coding style:

  1. It emphasizes the intention of the code.
  2. Reading it is a predictable and natural process.
  3. It avoids misleading notation.

Different languages will have different coding styles, but only because different readers disagree on what best depicts intention, what feels more natural, and what is misleading. Java and C# are very similar languages, but they have slightly different coding styles because their readers disagree on a few of these points.

There’s no single best coding style. No guidelines should be imposed on a team without considering the preferences of each individual. I am pretty sure that most will disagree with some of my guidelines. Heck, even I may disagree in a year or two. The important thing to keep in mind is that a code style guide should be owned by the team, and it should be flexible to adapt to new language constructs, or changes in company culture. You should use my guidelines as a starting point, but feel free to adapt them to your team.

Downward arrows, and downward alone, lead you to the goal of the action.

When reading a book, you know that you’re approaching the end of the book as you finish a paragraph and move down to the next. That’s the natural reading direction agreed by all of us, even by different cultures. That’s as natural as it gets!

The same should happen in code. With every downward movement of your eyeballs, must come the sensation of progress towards the goal.

A code style guide for OutSystems (2)

Interestingly, all text-based programming languages have this guideline built into them. Code always flows downward on Java or C#. There’s no need to even state the guideline.

But it’s different in OutSystems, and developers are tempted to be creative on which direction to layout the code. A classic example is the “snake” pattern, where code is laid out alternating left-to-right and right-to-left rows. This comes naturally from developers working with wide screens, as they try to fit as much code as possible into their screen.

A code style guide for OutSystems (3)

(Video) Code Style Guide, OutSystems and AWS Summit & Forge Updates - ICYMI 4

Here’s the problem with snakes: they bite. These ones will bite the unfortunate developers that happen to work on a smaller screen.

Let’s go back to our principles, and evaluate how poor this layout is. It does not emphasize your code, but only how big your screen is. And it requires you to alternate reading directions, left-to-right then right-to-left and back again. Very unnatural, unless you’re Leonardo da Vinci.

Stick with vertical flows. If you don’t like leaving half of your screen blank, hey, here’s a nice thing you can do with it: document your code.

Choose the most important branch of an if, and branch it to the right.

If nodes usually have a “most important” branch, and a “less important” one. By “most important” I mean the branch that is expected to be executed more often, or the branch which is simply more important in terms of business value. This branch should move to the right, and the other branch should continue straight down.

A code style guide for OutSystems (4)

By setting the most important of the two branches aside, we’re emphasizing it. We’re punctuating it and giving it more space to be written.

A code style guide for OutSystems (5)

Can’t decide which branch is the “most important?” Choose the most complex branch.

Both branches are equally important and equally complex? Do you really need a guideline for everything? Just flip a coin or something!

I should add that some developers prefer to split both branches in downward diagonals, in what is called a “checkers” pattern, if both branches are equally important and symmetric. I find this works well for short branches.

Nested ifs and indentation

When laying out nested ifs, just apply the same guideline at each level. You will find this creates multiple vertical code paths, each path related to a particular possible execution. For example, in the picture below, we can see there are 3 possible execution paths. Path 1 doesn’t execute anything. Path 2 appends a message item to a list. And path 3 sets a business field.

It’s clear at a glance that only one of these paths will execute. It’s also clear that Path 3 is considered the “most important” path, meaning that it’s the one that produces the most value.

A code style guide for OutSystems (6)

This effect results in a vertical alignment that is very similar to that of indentation. So let’s define the indentation level of a node as the horizontal separation between itself and the leftmost branch. The leftmost branch, in case you’re wondering, is always aligned with the Start node. So the indentation is just the horizontal displacement between a node and the Start node.

For example, the “Set Business Field” node above has indentation level of 2, because it is separated from path 1 by 2 horizontal spaces.

Just like in traditional programming languages, the indentation level is equal to how many ifs and loops are nested. And, you might have learned this, too many nested ifs and loops indicate poor architecture and code abstraction. So well-architected code will naturally be vertical, reinforcing Guideline 1.

True vs False

Some teams decide to differentiate the True and False branches, usually by specifying that the True branch should always move down. I have avoided any distinction between True and False, and my guideline is simply based on “most important” branch, which could either be True or False.

(Video) How to create an OutSystems Custom Portal Type Style Guide

I think I need to explain why I took that route. So here’s my thoughts on the discussion. And remember: there’s no single best coding style, so if you don’t agree with my reasoning, feel free to adapt the guidelines to your team.

A code style guide for OutSystems (7)

Often one of the branches of an if node is empty. You can see an example in the image on the left. In this case, it makes sense to me that the empty branch continues down, and the non-empty branch to move right.

If we want all True branches to move down, we would need to swap the branches in the image, and negate the condition to “Is not on hold?”. And this is the problem I have with that rule: it forces the developer to change the code just to comply with it. I would rather leave at the developer’s discretion which condition reads better.

I have gone through the arguments for keeping True down, and they all seem related to validations or exception handling. I think those scenarios are specific enough to have their own set of guidelines, so let’s talk about them.

Exceptions branches to the right, even if it’s not the “most important” branch

Let’s see what would happen if we applied Guideline 2 to a code that handles validations or exceptions.

A code style guide for OutSystems (8)

Let’s take the code on the left, in which there are 3 if nodes. According to Guideline 2, we should branch the most important branch to the right. I think you will agree, on all branches of the code above, the most important is the one that continues down. So it seems, we have a violation of Guideline 2.

However, to blindly apply Guideline 2 here, means that we end up with the monstrosity on the right. All if nodes have the most important branch to the right… but it doesn’t look natural, nor is it emphasizing anything. And the code is mostly horizontal now. Outrageous!

So, in this case, we should stick with the pattern on the left. We can generalize this further by saying that exceptional code branches to the right, regardless of its importance. We define exceptional code by any short if branch that terminates in an End node or Raise Exception node.

Horizontal exceptional code

A code style guide for OutSystems (9)

You might have seen code like the one above. This is an example of an exceptional code, found in a Save screen action, and related to form validations. The typical layout is horizontal, as shown above.

Doesn’t this violate Guideline 1? Let’s review what it says: downward arrows, and downward alone, lead you to the goal of the action.

The words “goal of the action” in the definition were chosen carefully. We should first ask: what is the goal of the Save screen action? It should be fairly clear that the goal is to persist user input. Now, the next question is: does the exceptional code move toward that goal?

No, that code doesn’t contribute to reaching the goal. Therefore, in this case, we are not violating Guideline 1, and we are not forced to vertically layout the validation code.

(Video) Building a Live Style Guide

Turns out exceptional code is… exceptional!

Start a for each cycle in an upward diagonal to the right.

A for each starts a loop in your code that might execute several times. It can be thought of as a branch that loops back on itself. Therefore, the same concept of indentation should apply here, and the code should be placed to the right, according to Guideline 2, and flow vertically as specified in Guideline 1.

To these rules, we add one more, that the first node of the for each should be placed above the for each node itself, as illustrated in the picture below.

Why start the loop diagonally? I have to be honest, my best answer is stylistic. I personally do this to give loops a distinct look.

I have seen other developers use the same layout, so it’s not just my personal taste. But I have also received the feedback that this contradicts Guideline 1, because there’s an upward movement. My best defense is that in any loop there will always be an upward movement.

One functional difference is that this layout brings the last node up and closer to the for each, which minimizes the distance between all nodes in the loop. The difference is not much, but it’s easier to see on smaller loops.

A code style guide for OutSystems (11)

It’s also important to remind that cycles can be created using if nodes, instead of for each nodes, for the equivalent of a while cycle in Java or C#. In this case, having a different layout applied to the if node helps distinguish it, and highlights the cyclic nature of the code, even in the absence of a for each node.

A code style guide for OutSystems (12)

Cycle continuation

Some cycles have nested if nodes, where one of the branches simply lead back to the for each node. These are called continuation if nodes. The continuation branch must move to the left, there’s really no other option. But what should we do with the other branch?

A code style guide for OutSystems (13)

If we follow Guideline 1, we should continue to layout the code vertically. If we follow Guideline 2, we should branch to the right. It seems in this case there’s no way to fulfill both guidelines, so we end up using Guideline 1 and give preference to a vertical layout.

Avoid overlapping arrows, even if it requires violating another guideline.

This guideline should not surprise you, most developers already follow it. The reason why we avoid overlapping arrows is simply to have a clearer visual flow.

(Video) How to style the UI elements using CSS & styles editor in OutSystems?

In some circumstances, following this guideline requires you to create empty nodes to direct the flow. The following example hopefully makes it clear.

A code style guide for OutSystems (14)

I use a white space in the label of empty assignments, which makes it look like it lacks a label. Some other teams use the “NOP” label, indicating there’s no operation in the assign. Other teams use an arrow symbol such as “>” to indicate the assign can simply be skipped. All of them are valid conventions.

I have also had the feedback that the usage of empty assigns is artificial, and might be a misleading notation to users that are not familiar with it. I completely agree. Hopefully in the future we’ll be able to avoid overlaps without abusing assigns. For now, it’s the best tool we have.

Intentionally align nodes that relate to each other.

A code style guide for OutSystems (15)

If two branches execute similar code, highlight that relationship by keeping the related nodes aligned. This intentional alignment will convey at a glance what is similar, and what is different, between the branches.

This strategy also makes it easier to perform changes on all branches. Suppose that, in the example above, we need to introduce a new assign node, before the append nodes. It’s far easier to select all append nodes with a rectangular selection, when they are already aligned.

A code style guide for OutSystems (16)

Exception handlers

Exception handlers can also benefit from alignment hints.

Indeed, an exception handler is kind of like an implicit branch, that jumps straight from the point where the exception happens, to the code in the exception handler. So, as weird as it may seem, it makes sense to apply Guideline 2. We should branch it to the right.

Align the exception handler to the right of the point where it is expected to happen.

In some cases, this alignment might not be possible. For example, if the same exception can come from multiple places, or if you just don’t know where it could come from. In those cases, just leave the exception handler in its usual place, aligned with the Start node.

By practicing these 6 guidelines, you will be writing OutSystems code that is easy and predictable to read, and consistent with other teams.

  1. Down is progress. Layout code vertically, from top to bottom.
  2. Branch to the right. Place the most important branch directly to the right.
  3. Exceptions to the right. Place exceptional code to the right, as if it were the most important branch.
  4. Cycles start on a diagonal. Start a cycle on a diagonal to the top and right.
  5. Avoid overlapping arrows. Re-arrange your code to avoid overlapping arrows.
  6. Align with intent. Keep related nodes aligned.

Should you start enforcing these guidelines in all of your projects? Absolutely not. At least, not until your team agrees that it’s the correct thing to do.

There’s no single best coding style. This is my attempt at codifying my experience of writing OutSystems code, and hopefully I made clear the compromises I’m making by converging on these guidelines.

FAQs

What is a live style guide OutSystems? ›

The visual guide to create a consistent and beautiful user experience on your apps. Styles. Guidance on basic design elements: typography, color, space and useful classes.

What language does OutSystems use? ›

The OutSystems IDE integrates with Visual Studio to enable developers to create extensions to the visual language. These extensions basically wrap standard C# code that can be used in the visual model. Developers are able to: Write their own C# code.

What is silk UI in OutSystems? ›

What is the Silk UI framework from OutSystems? In case you're not familiar with the Silk UI framework, it allows low-code developers to build amazing web and mobile user interfaces with great UI all with drag-and-drop movements, without any coding.

What is OutSystems community? ›

Community-Built App Repository

The OutSystems Forge is a collaborative repository of reusable open code modules shared by the entire Community. Access the connectors, UI components, business solutions, and “how to” samples you need to speed up both app delivery and onboarding.

Can you code in OutSystems? ›

Yes. OutSystems enables developers to use custom code to integrate with enterprise systems. OutSystems has out-of-the-box capabilities that allow seamless integration via SOAP, REST, or SAP APIs.

How hard is OutSystems? ›

OutSystems is a very easy to use tool, but in the end, what you are doing with it is in fact programming.

Is OutSystems worth learning? ›

For countless reasons, OutSystems proves to be an excellent option amongst the available enterprise web & mobile apps development platforms. It adopts low-code technology, which, as per Gartner, is the future of application development.

How do I create an Outsystem dashboard? ›

How to use Chart widgets for creating dashboards or reports in ... - YouTube

How do media queries work in OutSystems? ›

You can inspect your application in the browser by clicking on F12, and at the top you will find mobile icon, where you will get the resolution of your screen. The above media query will be applicable to the device size of max width 640px and below than that. You need to apply media query based on your screen size .

What types of applications can be created in OutSystems? ›

OutSystems allows you to create virtually any type of enterprise web and mobile application, given its openness and extensibility.

What is OutSystems MVP? ›

The OutSystems Most Valuable Professionals Program recognizes these valuable experts and introduces them to the OutSystems ecosystem of partners and customers as the elite developers in the market.

What is an Outsystem developer? ›

OutSystems is a low-code development platform for the development of mobile and web enterprise applications, which run in the cloud, on-premises or in hybrid environments.

Is OutSystems a language? ›

Outsystems is a low-code programming system. It helps developers by creating the code for them. It does this by visualizing the processes. OutSystems itself is built in a coding language .

What is OutSystems developer? ›

OutSystems is a low-code development platform for the development of mobile and web enterprise applications, which run in the cloud, on-premises or in hybrid environments.

Is OutSystems easy? ›

At the end of the day, however, OutSystems is a powerful and relatively easy to learn low-code tool that will allow you to quickly start building your own applications. And, as we know, the demand for programmers, including low-code ones, is constantly growing.

What is OutSystems low-code? ›

Low-code is a software development approach that enables the delivery of applications faster and with minimal hand-coding. Low-code platforms are a collection of tools that enable the visual development of applications through modeling and a graphical interface.

By practising these 6 guidelines, you will be writing OutSystems code that is easy and predictable to read and consistent with other teams | PhoenixDX

Do you need a guideline for everything?. Exceptions branches to the right, even if it’s not the “most important” branch.. These are indeed the “exceptions” to the rule.Let’s take the code above, in which there are 3 if nodes.. According to Guideline 2, we should branch the most important branch to the right.. Therefore, in this case, we are not violating Guideline 1, and we are not forced to vertically layout the validation code.. Some cycles have nested if nodes, where one of the branches lead back to them for each node.. The layout on the right emphasises related nodes on separate paths by aligning them on a horizontal axis.If two branches execute similar code, highlight that relationship by keeping the related nodes aligned.

Today, numerous businesses depend on digital platforms. And that means it’s critical for applications to adapt to user needs over time. A live style guide can optimize this process. Let’s take a look at how.

Similar to a normal style guide, a live style guide offers a set of rules for the creation of applications.. First and foremost, a live style guide provides your development team with “living” elements that follow the visual rules of a style guide.. We were partners with the OutSystems team that developed the Silk UI Framework , which accelerates front-end development, solves UI issues and enables organizations to deliver beautiful experiences that are popular with users.. With the knowledge we have acquired through our close partnership with OutSystems, we have developed a Live Style Guide that supports the development of new projects.. With this live style guide, it’s possible to deliver an OutSystems application with 80% of the assets needed to develop the different screens in the application.. After receiving the wireframes (screen design) from the UX phase, the UI team will design a theme focused on the application’s branding with all the Silk UI Framework patterns, along with any other screens and patterns devised during the UX phase, providing a high-quality visual identity to the applications.. Development In this phase, the development team creates the theme designed during the previous phase, develops patterns devised during the UX phase, and customizes all the Silk UI Framework patterns with the branding of this same theme.

What can you really build with low code? You’ll find out in this article. Respond to the pressure of delivering more and faster with OutSystems.

Many low-code tools have no-code features embedded to allow citizen developers (non-professional developers with little to no app dev experience) to build simple, B2E applications almost exclusively using prebuilt templates, connectors, APIs, and logic.. With low-code, development teams can build new web and mobile apps that involve data, business logic, and external services, such as SaaS services, in less than three months.. So, with low-code you can indeed build business process applications but, for some platforms, if you need to integrate those apps to other systems on-premise, you’ll need to do a lot of hand-coding.. Modern application platforms like OutSystems give your fusion teams the simplicity of low-code development but are integrated into a full-stack application development platform.. Low-code allows development teams to build web and mobile SaaS and ISV (independent software vendor) applications using cool templates.

Documentation can be a divisive subject between developers. How much is too much? How little is too little? How should it be formatted? Do you need an external documentation resource or are the code comments and definitions enough?

With OutSystems, you are given the benefit that your code becomes its own documentation.. Things like “Meaningful names (e.g. ‘Customer’ instead of ‘Cstr’)” and “Set the example string of Expressions” can make screens and actions easier to understand.. Here’s how OutSystems makes it easy to document as you go and simplifies the sharing of documentation.. Across the platform, OutSystems makes it easy to make your code more readable.. These descriptions appear in a tooltip in the action flow and as a description when being used as a function.. Description in an action flow. OutDoc OutDoc is a Forge component created by OutSystems that automatically generates documentation for your applications.. The description for the entire web service can be written in markdown, meaning you can include better formatting as well as external links.. If you write descriptive names for your actions and variables, descriptions may not even be required.

Read how code reusability with the low-code development platform - OutSystems accelerates digital transformation & increases productivity.

Code reusability in OutSystems refers to building a new app (mobile and web) using pre-existing components.. It also helps them reuse existing elements or modules multiple times on all layers of application development – UI, business logic, and database.. It also allows the customization of apps by creating configuration components that can guide the reusable modules on how to function for a specific app, giving all the applications a robust architecture.. Since code reusability enables developers to work with already simplified, tested, and debugged modules, it reduces the complexity of the end application and helps them maintain consistency while creating new apps or updating the existing ones.. Creating an enterprise application by reusing code requires only a few developers.. They can build reusable components and develop applications based on business users’ requirements in less time.. Developers should set permissions on the reusable components so that it is possible to enable governance of shared modules.. Data tables should be consistent and placed in a separate module at all times as they are shared amongst web and mobile applications.

All 3 low code platforms cater to all kinds of businesses with feature-packed GUI, integration capabilities, drag-drop functionality, cloud, and so on.

Gartner predicts that low code application development platforms will be responsible for more than 65 percent of all app dev activity by 2024, while Forrester expects the low code market to represent $21B in spending by 2022.. Low code platforms offer a user-friendly and robust environment to both coders and non-coders to help them build applications faster and smoother.. These platforms help them with everything including the development and deployment of applications, seamless integrations, unique interface design, and many more with minimal coding.. OUTSYSTEMS OutSystems is the most popular and widely used modernized low code platform that is power-packed with AI automation, visualization tools, integration assistance, cloud architecture, and last but not least quick drag and drop features.. APPIAN Another popular low code platform, Appian, helps you deliver powerful and feature-packed applications using interactive GUI.. OUTSYSTEMS OutSystems' low-code platform helps teams build applications faster using the dashboard and pre-defined templates that provide you with interactive, easy-to-use, and hassle-free GUI.. APPIAN Appian platform facilitates you building of powerful applications and business processes in quick simple steps.. The three platforms Mendix, OutSystems, and Appian, offer you best-in-class features with complete interface control and real-time monitoring of all applications.. Low code platforms provide you with endless digital solutions, be it about developing applications, streamlining business processes and workflows, managing third-party integrations, and so on.. It makes low code app creation easier and faster with quick drag and drop tools that allow users to build reliable and scalable apps.. Although all three platforms offer excellent services for low code development and app deployment, they do face certain challenges when developing applications.

Outsystems vs Mendix: compare which is the best low code development platform. Know difference between outsystems and medix.

Although there are numerous top low code platforms available based on various business needs, Mendix and OutSystems are two of the most popular low-code development platforms .. OutSystems is the most popular and widely used modernized low code platform, with AI automation, visualization tools, integration assistance, cloud architecture, and a quick drag and drop process.. Enterprise development teams and developers can use the platform to build, integrate, and deploy powerful multi-device applications quickly.. Simple visual low code modeling tools A wysiwyg no code IDE Cloud-native architecture and collaborative development Embrace innovative applications with AI and cognitive services Automation of the entire process and continuous integration. They can quickly improve their internal business processes with low code platforms, resulting in increased efficiency and a better customer experience.. Starting with OutSystems, here are some features you can take advantage of during application development:. Without any coding experience, you can create and deploy scalable and robust applications.. The platform also includes a powerful app editor that allows you to automatically create tabs as you go.. These platforms include everything you need to create the best apps.. Mendix’s integration with the enterprise apps requires improvement.. Mendix Vs OutSystems making a choice between them can be difficult because both products provide excellent options as enterprise low-code platforms that cater to a wide range of business users.

Videos

1. OutSystems Training Webinar - Designing for OutSystems Applications
(OutSystems)
2. Top front-end techniques for OutSystems
(OutSystems)
3. Front End Development: From Mockup to Coding
(OutSystems)
4. Hi Masterclass - How to Create an App Template for OutSystems
(Hi Interactive)
5. CSS Best Practices
(OutSystems)
6. Front-End OutSystems 360 | Hi Interactive
(Hi Interactive)

You might also like

Latest Posts

Article information

Author: Terrell Hackett

Last Updated: 09/14/2022

Views: 5409

Rating: 4.1 / 5 (52 voted)

Reviews: 91% of readers found this page helpful

Author information

Name: Terrell Hackett

Birthday: 1992-03-17

Address: Suite 453 459 Gibson Squares, East Adriane, AK 71925-5692

Phone: +21811810803470

Job: Chief Representative

Hobby: Board games, Rock climbing, Ghost hunting, Origami, Kabaddi, Mushroom hunting, Gaming

Introduction: My name is Terrell Hackett, I am a gleaming, brainy, courageous, helpful, healthy, cooperative, graceful person who loves writing and wants to share my knowledge and understanding with you.