APEX Principles of Good Practice

These principles are designed to define high standards and reflect the best practices for application development using Oracle APEX in order to advance the goal of delivering quality software systems. The principles seek to maximize these qualities: Declarative; Discoverable; Explainable; and Maintainable.

Declarative systems favor the what over the how and prioritize data over code.

Discoverable systems are easy to read. Inter-dependencies are easy to follow and instrumentation exists to trace execution.

Explainable systems are easy to reason about and understand. Inner workings reveal themselves and decision points are both understandable and traceable. An explainable system is easy to recognize as a restatement of the underlying requirements.

Maintainable systems are easy to debug and enhance. They are low-risk when altering and upgrading their underpinnings. Maintainable systems avoid incidental complexity.

Design and build with other developers in mind
Prioritize declarative
Be intentional about working around or against the framework
Use a design methodology
Practice good naming and commenting conventions
Static values should be meaningful
Pages should be self-contained
Preserve dependencies between APEX and the database
Avoid writing code inside APEX components
Decompose code into small units

Design and build with other developers in mind

Remember that complexity is not merely a factor of the number of components or functions or lines of code or characters in a name. Write once / maintain forever means prioritizing reading code over writing code. Short names and abbreviations and condensed code may save a few keystrokes and whitespace but require more effort for the reader who is also tasked with supporting the live system and fixing your defective code.

The goal is to develop an application that is self documenting because no one in the future, including you, will have access to your current mental state.

Prioritize declarative

Where possible find a solution using the declarative characteristics of APEX. The declarative nature of APEX is its superpower and helps to achieve discoverability and maintainability.

When logic is less discoverable it is easier to overlook and become a source of defects.

Be intentional about working around or against the framework

There may be times where the declarative characteristics of APEX will not be flexible enough to accommodate your conception of the problem. Notice this and first see if you can reconceive the problem. Even if it means creating new page items and more than one calculation it may be worth considering the tradeoffs with regard to meeting the quality goals.

Where you leave the road of the declarative framework, leave good road signs for others to follow.

Use a design methodology

APEX excels in part due to its inherent discoverability. A developer can easily focus on building functionality knowing the framework helps make things easy to find. But this does not mean one will know where to look and why. Lack of up front design increases the chances of redundancy and incidental complexity that comes from coding around a sunk cost.

Make design choices up front and allow them to guide you in choosing your methods of implementation. To do otherwise assumes that every developer would make the exact same choices and hence you have no reason to think about or explain your choices.

Practice good naming and commenting conventions

Systems built with APEX have the capability of reading like an instruction manual or requirements document. Names can explain what a component does and comments can explain any non-obvious complexity.

Almost everything in APEX has a Name and Comment attribute. Use the Name to explain what it does and under what conditions. Use the Comment to further explain any rationales.

Just like a function name helps signal what it does, using good naming will enhance discoverability. And just like good comments in code, good comments (in the comments attribute) enhances explainability.

The goal should be to help the reader understand what they cannot easily reason about from the other attributes and help them determine where to dig more deeply.

Static values should be meaningful

Having a condition like “PXXX_ITEM = 5” is meaningless on its face. Anyone reading this will need to understand what and why the 5. Packaged constants are a great way to name magic values in PL/SQL. APEX provides Substitution Strings for this.

Using a named value from a packaged constant or an Application Substitution String helps the system become more explainable. Using a named function increases reuse and decreases chances for redundancy. These techniques also help provide a single point of definition so that magic values are easier to maintain.

The goal is to be able to read the system like a book with a detailed index and glossary.

Pages should be self-contained

Pages should not reference items in other pages and use of application level variables should be carefully considered. The decision to use item state from outside the page should have sound reasoning and the tradeoffs considered should put heavy weight towards keeping all state in the page.

The goal is to reduce potential sources of defect, simplify maintenance by reducing shared dependencies, and ease testing and debugging.

Preserve dependencies between APEX and the database

Preserving dependencies between APEX and the database is an important consideration for maintenance. Two primary sources of disconnect are column name aliases in SQL and dynamic SQL and PL/SQL.

Avoid writing code inside APEX components

Once your application grows beyond simple CRUD (crude) operations you will reach a point where PL/SQL is needed. One great option for this is to put all this code into the database inside packages and let APEX work as a thin layer for the user interface. This goes for code in conditions and validations and computations..anywhere there is a box for PL/SQL code.

The tradeoff of making it slightly less visible within APEX allows the database to manage things like dependencies and security. Here procedure naming and parameter naming are important to help make it so the developer in APEX knows when and where to look further into the database.

To make your stored code easier to test and more portable, avoid reading or writing session state in code. Instead use parameters to pass in any needed session state values. Use function return values or out parameters to catch any values needed for setting session state.

For PL/SQL best practices refer to

• Oracle PL/SQL Best Practices By Steven Feuerstein
• Trivadis PL/SQL and SQL Coding Guidelines
• Official Oracle Documentation.

Decompose code into small units

For code inside the database and code inside APEX, it is best to decompose first and then compose later as necessary. Compose within a single code block only when necessary. APEX gives you an unlimited number of records to store components that call PL/SQL.

Lines of code increase complexity far more than many small components in APEX.

Remember, you are building a tool, not just using a tool. Imagine the enjoyment a craftsperson gets from using a good tool.