DEV Community: Greg Jarmiolowski

Use a design methodology

Greg Jarmiolowski — Fri, 25 Sep 2020 06:03:00 +0000

Making design choices up front saves you headaches later. You can't make every decision in the beginning but you can set parameters and goals to guide later decision making.

Start simple with some conventions about how you organize code and how you arrange your applications. Some of these conventions can be carried across projects so there are fewer decisions to be made and regularity makes it easier as you go.

Before I start designing a system I try to get lots of input from potential users about how they work and what they need. I solicit documents and spreadsheets they use to get myself immersed in their data.

Then I start to create documentation for what I learned by defining terms first. Having an agreed upon vocabulary helps aid in the accurate exchange of information. Don't expect the customer to always realize when different divisions use the same name for different concepts. These concepts might even change depending on the time of year.

I borrow from Agile and create actors and stories. I get users together to play a game called Focus Mapping with the stories which helps everyone agree on priorities.

Once it comes to designing the database schema I look at the Data Model Resource books for anything I can reuse. Here it helps to think about data not in terms of the semantics but in terms of the shapes. This is where having some exposure to SHACL or GraphQL can help you see the different ways the same schema can be viewed. What you think is the shape for the entities might really just be one representation.

Of course normal forms are important but you need to be able validate the relationships and especially the shape constraints. Finding out you have a single attribute where you needed a list is one of the most common triggers for a schema change, and these changes often are the most work.

I'm a big fan of canvas systems. These can be great for defining up front some set of information and decisions that are needed to build the system. They also serve as a handy and concise communication tool. See examples here and here.

Find what works for you but have some idea of the process you are going to follow before you start wandering. Communicating this to clients also sets the stage and helps you know up front where there might be resistance or where information you need may be hard to obtain or validate.

Be intentional about working around or against the framework

Greg Jarmiolowski — Fri, 25 Sep 2020 05:14:11 +0000

The first thing I want you to consider about the APEX framework is all that it gives you for free.

For starters, the framework is highly instrumented via the debug log. Each time a page item has a value changed you get a message in the debug log. Each time an authorization or condition is evaluated you get a message.

Now that may not seem like a powerful message but maybe it will if you just recall all the times you needed to debug something and found yourself adding debug statements to your application.

Here's an extreme opinion to get you thinking about this:

Debug statements are a code smell

Feel free to disagree. It's just a strawman to get you thinking that maybe adding debug statements isn't the best solution.

The framework also is nicely structured for editing, discovery and reporting. If you aren't looking at the APEX Views you are missing out on a lot of the power APEX gives you for free.

Also it is easy to "play computer" in your head about the framework. One can more readily understand what will happen if they change something declarative than something in code.

Every time you go around the framework you are circumventing the natural methods. Other developers will be expecting and looking for the natural methods. You, looking back at your code in a month or two, will be expecting and looking for the natural methods.

So, be intentional about working around or against the framework.

So add those debug statements and other signposts to help others see that you have forged your own path through the garden. Add some comments to explain how it works and why it was necessary. The next time someone, even you, looks at it they might see another path.

Prioritize declarative

Greg Jarmiolowski — Thu, 07 May 2020 03:47:57 +0000

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

One beautiful thing about APEX is that everything resides in this relational container. Used correctly everything can be found easily. You can determine all your dependencies and make changes without the risk of not knowing what you missed.

When you look at the builder and the various ways it can be laid out, consider that you can create your own special view of that same data .. as long as you treat it as data. When I open a new application I love that I can easily reason about the easy parts, like how does a page render, what does it render?

When several Conditions apply to the execution of some code it may be better to create multiple Processes, one for each Condition, than to put the Conditions inside the Process code itself. It can be tempting to put them all in one Process so you have them all in one place. But APEX is “one place” too and you can organize your code inside multiple Processes and achieve something that reads like a boxes and arrows diagram. Add in some verbose naming and the reader can understand what these processes do without digging into code.

Instead of declaring local variables inside an anonymous PL/SQL block, create page items and compute them. It might seem like overkill to do this but then when you need to debug this you get session state and logging for free.

Design and build with other developers in mind

Greg Jarmiolowski — Thu, 07 May 2020 03:34:28 +0000

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.

Having the opportunity to work on a system you developed years ago is a real eye opener. The key takeaway for me was that I am now a different person and what I did at the time is not obvious to me.

Reading code is the last thing most of us think about when we build. And in APEX code is often interpreted from little bits of data. How we put that data together is important.

One of the things I like the most about APEX is the structure is familiar and consistent. I can usually open any application and find my way around. But once I encounter code blocks and complex queries, a different style of reading comes into play.

Incidental complexity is how we create messes and so the overarching message here is to minimize and document complexity. The opposite of complex is simple (not easy). This means at hand, easy to reason about, clear.

Consider, will debugging this require me to go look up a bunch of things? How many balls do I need to put into the air in order to understand what is happening right here and now as I debug or support a customer or add an enhancement?

Towards APEX of Good Practice

Greg Jarmiolowski — Sun, 03 May 2020 16:57:44 +0000

I recently posted an article "APEX Principles of Good Practice".

The idea for this format came from my job at the National Association of Independent Schools. NAIS published a series of Principles of Good Practice for different areas of school operations that were extremely popular. To me this was a very compelling idea. Rather than tell schools how to run themselves, they provided a framework for decision making. So rather than tell others how to design and code in APEX, I thought I would offer a framework for decision making.

The principles start with an explanation of their goals. The principles seek to maximize these qualities: Declarative; Discoverable; Explainable; and Maintainable. There can be other goals but I chose these as a framework for how to weigh tradeoffs. Each of the 10 principles is rooted in one or more of the four goals.

The perspective I wrote from comes from years of experience and, more recently, working on a large system that is the accumulation of years of work by several different developers, in succession. It's obvious that each of these developers, including myself, had different ways of building. Most of them, myself included, appear to have optimized for laziness. That is to say, they needed to get the most done in the shortest amount of time.

I think that most developers struggle with producing versus engineering. Time is never on our side which means we aim to keep it simple but often really choose easy.

There are no right or wrong answers, just tradeoffs. I hope the principles help make those tradeoffs more conscious.

APEX Principles of Good Practice

Greg Jarmiolowski — Sun, 03 May 2020 16:29:01 +0000

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.