Architecture naming conventions — for modules in OutSystems

(Target audience: Developers, Architects, and Tech Leads)

In our OutSystems applications architecture, naming conventions are a way to ensure consistency and maintainability of our code.

Motivation

This article presents an extended description of naming conventions for OutSystems modules [1]. The information is already available in online materials, but is now condensed here from dispersed sites.

Besides direct readability, inside an application code context (and note there are different opinions about understandability of these names), these naming conventions are used to minimize architecture violations risks.

A good architecture aims to promote abstraction, reusable services, isolated end-user processes, and managed references.

Architecture Rules

Always nice to know the 3 architecture rules, of a correct architecture:

1. No upward references: upward references indicates services not isolated at the correct layer.

2. No side references for orchestration or end-users: end-user modules should not provide services, to not interfere with other’s lifecycles.

3. No cycles between services: a service can depend or extend another service. A cycle typically indicates that concepts are not correctly isolated.

Conventions

Any module name, with an “_” and a suffix matching a certain pattern (convention), is a candidate to be auto-classified by Discovery and associated to the correct layer in our Architecture Canvas [3].

Besides the normal conventions, I use the suffix “_UI” to distinguish an Entry module from other Front-End modules, and an “_OAPI” to isolate OutSystems API services.

Validation

This information is also used by Architecture Dashboard. By the way, the March 5th release contains a new validation feature: the ability to see details about module references that compose an architecture violation (and these alerts are now inside this tool).

Here I described a limited number of naming conventions. If you have more naming conventions suggestions, useful and relevant to be incorporated into this model, write me a message. Feedback is welcomed!

References

[1] OutSystems — Module Naming

[2] OutSystems — Validating Applications Architecture

[3] OutSystems — The Architecture Canvas

OutSystems Tech Lead / Senior Agile Developer / Software Engineer, working in DevOps teams to deliver rapid applications following Scrum.