Skip to content

Introduction

This document describes rules and recommendations for developing applications using the PL/SQL & SQL Language.

Scope

This document applies to the PL/SQL and SQL language as used within Oracle Databases and tools, which access Oracle Databases version 11g Release 2 or later.

Document Conventions

SQALE (Software Quality Assessment based on Lifecycle Expectations) is a method to support the evaluation of a software application source code. It is a generic method, independent of the language and source code analysis tools.

SQALE characteristics and subcharacteristics

Characteristic Description and Subcharacteristics
Changeability The capability of the software product to enable a specified modification to be implemented.
  • Architecture related changeability
  • Logic related changeability
  • Data related changeability
    Efficiency The capability of the software product to provide appropriate performance, relative to the amount of resources used, under stated conditions.
    • Memory use
    • Processor use
    • Network use
    Maintainability The capability of the software product to be modified. Modifications may include corrections, improvements or adaptation of the software to changes in environment, and in requirements and functional specifications.
    • Understandability
    • Readability
    Portability The capability of the software product to be transferred from one environment to another.
    • Compiler related portability
    • Hardware related portability
    • Language related portability
    • OS related portability
    • Software related portability
    • Time zone related portability.
    Reliability The capability of the software product to maintain a specified level of performance when used under specified conditions.
    • Architecture related reliability
    • Data related reliability
    • Exception handling
    • Fault tolerance
    • Instruction related reliability
    • Logic related reliability
    • Resource related reliability
    • Synchronization related reliability
    • Unit tests coverage.
    Reusability The capability of the software product to be reused within the development process.
    • Modularity
    • Transportability.
    Security The capability of the software product to protect information and data so that unauthorized persons or systems cannot read or modify them and authorized persons or systems are not denied access to them.
    • API abuse
    • Errors (e.g. leaving a system in a vulnerable state)
    • Input validatation and representation
    • Security features.
    Testability The capability of the software product to enable modified software to be validated.
    • Integration level testability
    • Unit level testability.

    Severity of the rule

    Blocker

    Will or may result in a bug; for example, an incorrect result or a runtime exception.

    Critical

    Will have a high/direct impact on the maintenance cost. May have an impact on runtime behavior; for example, incomplete audit data or slower runtime performance.

    Major

    Will have a medium/potential impact on the maintenance cost. May have an impact on runtime behavior; for example, higher memory consumption.

    Minor

    Will have a low impact on the maintenance cost. No impact on the runtime behavior.

    Info

    Very low impact; it is just a remediation cost report. No impact on runtime behavior. For example, a NOSONAR marker comment.

    Keywords used

    Keyword Meaning
    Always Emphasizes this rule must be enforced.
    Never Emphasizes this action must not happen.
    Avoid Emphasizes that the action should be prevented, but some exceptions may exist.
    Try Emphasizes that the rule should be attempted whenever possible and appropriate.
    Example Precedes text used to illustrate a rule or a recommendation.
    Reason Explains the thoughts and purpose behind a rule or a recommendation.
    Restriction Describes the circumstances to be fulfilled to make use of a rule.

    Validator support

    The tool db* CODECOP (see the "Tool Support" chapter) cannot support all the guidelines in this document. Those guidelines that are not supported by db* CODECOP validators are marked like this:

    Unsupported in db* CODECOP Validators

    Reason why the specific guideline is not supported by the validators.

    The db* CODECOP repository documents the details of validator limitations.

    Why are standards important

    For a machine executing a program, code formatting is of no importance. However, for the human eye, well-formatted code is much easier to read. Modern tools can help to implement format and coding rules.

    Implementing formatting and coding standards has the following advantages for PL/SQL development:

    • Well-formatted code is easier to read, analyze and maintain (not only for the author but also for other developers).
    • The developers do not have to define their own guidelines - it is already defined.
    • The code has a structure that makes it easier to avoid making errors.
    • The code is more efficient concerning performance and organization of the whole application.
    • The code is more modular and thus easier to use for other applications.

    We have other standards

    This document only defines possible standards. These standards are not written in stone, but are meant as guidelines. If standards already exist, and they are different from those in this document, it makes no sense to change them.

    We do not agree with all your standards

    There are basically two types of standards.

    1. Non-controversial

      These standards make sense. There is no reason not to follow them. An example of this category is G-2150: Avoid comparisons with NULL value, consider using IS [NOT] NULL.

    2. Controversial

      Almost every rule/guideline falls into this category. An example of this category is 3 space indention. - Why not 2 or 4 or even 8? Why not use tabs? You can argue in favor of all these options. In most cases it does not really matter which option you choose. Being consistent is more important. In this case it will make the code easier to read.

    For very controversial rules, we have started to include the reasoning either as a footnote or directly in the text.

    Usually it is not helpful to open an issue on GitHub to request to change a highly controversial rule such as the one mentioned. For example, use 2 spaces instead of 3 spaces for an indentation. This leads to a discussion where the people in favor of 4 spaces start to argument as well. There is no right or wrong here. You just have to agree on a standard.

    More effective is to fork this repository and amend the standards to fit your needs/expectations.