diff --git a/docs/1-introduction/introduction.md b/docs/1-introduction/introduction.md index 3a7a9814..5d8b45e3 100644 --- a/docs/1-introduction/introduction.md +++ b/docs/1-introduction/introduction.md @@ -4,7 +4,7 @@ This document describes rules and recommendations for developing applications us ## 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. +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 diff --git a/docs/2-naming-conventions/naming-conventions.md b/docs/2-naming-conventions/naming-conventions.md index 85ef4ec8..34bb9663 100644 --- a/docs/2-naming-conventions/naming-conventions.md +++ b/docs/2-naming-conventions/naming-conventions.md @@ -8,14 +8,14 @@ 4. Avoid long abbreviations. Abbreviations should be shorter than 5 characters. 5. Any abbreviations must be widely known and accepted. 6. Create a glossary with all accepted abbreviations. -7. Never use Oracle keywords as names. A list of Oracles keywords may be found in the dictionary view `v$reserved_words`. +7. Never use keywords as names. A list of keywords may be found in the dictionary view `v$reserved_words`. 8. Avoid adding redundant or meaningless prefixes and suffixes to identifiers.
Example: `create table emp_table`. 9. Always use one spoken language (e.g. English, German, French) for all objects in your application. 10. Always use the same names for elements with the same meaning. ## Naming Conventions for PL/SQL -In general, Oracle is not case sensitive with names. A variable named personname is equal to one named PersonName, as well as to one named PERSONNAME. Some products (e.g. TMDA by Trivadis, APEX, OWB) put each name within double quotes (") so Oracle will treat these names to be case sensitive. Using case sensitive variable names force developers to use double quotes for each reference to the variable. Our recommendation is to write all names in lowercase and to avoid double quoted identifiers. +In general, the Oracle Database is not case sensitive with names. A variable named personname is equal to one named PersonName, as well as to one named PERSONNAME. Some products (e.g. TMDA by Trivadis, APEX, OWB) put each name within double quotes (") so the Oracle Database will treat these names to be case sensitive. Using case sensitive variable names force developers to use double quotes for each reference to the variable. Our recommendation is to write all names in lowercase and to avoid double quoted identifiers. A widely used convention is to follow a `{prefix}variablecontent{suffix}` pattern. @@ -254,6 +254,6 @@ Examples: We see a table and a view as a collection. A jar containing beans is labeled "beans". In Java we call such a collection also "beans" (`List beans`) and name an entry "bean" (`for (Bean bean : beans) {...}`). An entry of a table is a row (singular) and a table can - contain an unbounded number of rows (plural). This and the fact that the Oracle database uses + contain an unbounded number of rows (plural). This and the fact that the Oracle Database uses the same concept for their tables and views lead to the decision to use the plural to name a table or a view. diff --git a/docs/4-language-usage/2-variables-and-types/1-general/g-2130.md b/docs/4-language-usage/2-variables-and-types/1-general/g-2130.md index e4fa721b..75b556c5 100644 --- a/docs/4-language-usage/2-variables-and-types/1-general/g-2130.md +++ b/docs/4-language-usage/2-variables-and-types/1-general/g-2130.md @@ -13,7 +13,7 @@ Your code will be easier to read as the usage of a variable/constant may be deri Type | Usage ------------------ | ----- -`ora_name_type` | Object corresponding to the Oracle naming conventions (table, variable, column, package, etc.). +`ora_name_type` | Object corresponding to the Oracle Database naming conventions (table, variable, column, package, etc.). `max_vc2_type` | String variable with maximal VARCHAR2 size. `array_index_type` | Best fitting data type for array navigation. `id_type` | Data type used for all primary key (id) columns. diff --git a/docs/4-language-usage/2-variables-and-types/1-general/g-2190.md b/docs/4-language-usage/2-variables-and-types/1-general/g-2190.md index 95837c4f..7e20ff6b 100644 --- a/docs/4-language-usage/2-variables-and-types/1-general/g-2190.md +++ b/docs/4-language-usage/2-variables-and-types/1-general/g-2190.md @@ -5,7 +5,7 @@ ## Reason -Be careful about your use of Oracle-specific data types like `rowid` and `urowid`. They might offer a slight improvement in performance over other means of identifying a single row (primary key or unique index value), but that is by no means guaranteed. +Be careful about your use of Oracle Database specific data types like `rowid` and `urowid`. They might offer a slight improvement in performance over other means of identifying a single row (primary key or unique index value), but that is by no means guaranteed. Use of `rowid` or `urowid` means that your SQL statement will not be portable to other SQL databases. Many developers are also not familiar with these data types, which can make the code harder to maintain. diff --git a/docs/4-language-usage/2-variables-and-types/2-numeric-data-types/g-2230.md b/docs/4-language-usage/2-variables-and-types/2-numeric-data-types/g-2230.md index 9603dd14..f0019bf9 100644 --- a/docs/4-language-usage/2-variables-and-types/2-numeric-data-types/g-2230.md +++ b/docs/4-language-usage/2-variables-and-types/2-numeric-data-types/g-2230.md @@ -7,7 +7,7 @@ `simple_integer` does no checks on numeric overflow, which results in better performance compared to the other numeric datatypes. -With Oracle 11g, the new data type `simple_integer` has been introduced. It is a sub-type of `pls_integer` and covers the same range. The basic difference is that `simple_integer` is always `not null`. When the value of the declared variable is never going to be null then you can declare it as `simple_integer`. Another major difference is that you will never face a numeric overflow using `simple_integer` as this data type wraps around without giving any error. `simple_integer` data type gives major performance boost over `pls_integer` when code is compiled in `native` mode, because arithmetic operations on `simple_integer` type are performed directly at the hardware level. +With Oracle Database 11g, the new data type `simple_integer` has been introduced. It is a sub-type of `pls_integer` and covers the same range. The basic difference is that `simple_integer` is always `not null`. When the value of the declared variable is never going to be null then you can declare it as `simple_integer`. Another major difference is that you will never face a numeric overflow using `simple_integer` as this data type wraps around without giving any error. `simple_integer` data type gives major performance boost over `pls_integer` when code is compiled in `native` mode, because arithmetic operations on `simple_integer` type are performed directly at the hardware level. ## Example (bad) diff --git a/docs/4-language-usage/2-variables-and-types/3-character-data-types/g-2330.md b/docs/4-language-usage/2-variables-and-types/3-character-data-types/g-2330.md index 1b28724a..31734a5a 100644 --- a/docs/4-language-usage/2-variables-and-types/3-character-data-types/g-2330.md +++ b/docs/4-language-usage/2-variables-and-types/3-character-data-types/g-2330.md @@ -5,7 +5,7 @@ ## Reason -Today zero-length strings and `null` are currently handled identical by Oracle. There is no guarantee that this will still be the case in future releases, therefore if you mean `null` use `null`. +Today zero-length strings and `null` are currently handled identical by the Oracle Database. There is no guarantee that this will still be the case in future releases, therefore if you mean `null` use `null`. ## Example (bad) diff --git a/docs/4-language-usage/2-variables-and-types/5-large-objects/g-2510.md b/docs/4-language-usage/2-variables-and-types/5-large-objects/g-2510.md index 97c0ca70..f6415905 100644 --- a/docs/4-language-usage/2-variables-and-types/5-large-objects/g-2510.md +++ b/docs/4-language-usage/2-variables-and-types/5-large-objects/g-2510.md @@ -5,7 +5,7 @@ ## Reason -`long` and `long raw` data types have been deprecated by Oracle since version 8i - support might be discontinued in future Oracle releases. +`long` and `long raw` data types have been deprecated by the Oracle Database since version 8i - support might be discontinued in future Oracle Database releases. There are many constraints to `long` datatypes in comparison to the `lob` types. diff --git a/docs/4-language-usage/3-dml-and-sql/1-general/g-3170.md b/docs/4-language-usage/3-dml-and-sql/1-general/g-3170.md index 44979572..e1cd033d 100644 --- a/docs/4-language-usage/3-dml-and-sql/1-general/g-3170.md +++ b/docs/4-language-usage/3-dml-and-sql/1-general/g-3170.md @@ -12,7 +12,7 @@ Oracle Database 12c ## Reason -Default values have been nullifiable until Oracle 12c. Meaning any tool sending null as a value for a column having a default value bypassed the default value. Starting with Oracle 12c default definitions may have an `on null` definition in addition, which will assign the default value in case of a `null` value too. +Default values have been nullifiable until Oracle Database 12c. Meaning any tool sending null as a value for a column having a default value bypassed the default value. Starting with Oracle Database 12c default definitions may have an `on null` definition in addition, which will assign the default value in case of a `null` value too. ## Example (bad) diff --git a/docs/4-language-usage/4-control-structures/1-cursor/g-4130.md b/docs/4-language-usage/4-control-structures/1-cursor/g-4130.md index 7594144c..cee5a3f2 100644 --- a/docs/4-language-usage/4-control-structures/1-cursor/g-4130.md +++ b/docs/4-language-usage/4-control-structures/1-cursor/g-4130.md @@ -5,7 +5,7 @@ ## Reason -Any cursors left open can consume additional memory space (i.e. SGA) within the database instance, potentially in both the shared and private SQL pools. Furthermore, failure to explicitly close cursors may also cause the owning session to exceed its maximum limit of open cursors (as specified by the `open_cursors` database initialization parameter), potentially resulting in the Oracle error of “ORA-01000: maximum open cursors exceeded”. +Any cursors left open can consume additional memory space (i.e. SGA) within the database instance, potentially in both the shared and private SQL pools. Furthermore, failure to explicitly close cursors may also cause the owning session to exceed its maximum limit of open cursors (as specified by the `open_cursors` database initialization parameter), potentially resulting in the Oracle Database error of “ORA-01000: maximum open cursors exceeded”. ## Example (bad) diff --git a/docs/4-language-usage/4-control-structures/1-cursor/g-4140.md b/docs/4-language-usage/4-control-structures/1-cursor/g-4140.md index 3cc277f2..5830b1c7 100644 --- a/docs/4-language-usage/4-control-structures/1-cursor/g-4140.md +++ b/docs/4-language-usage/4-control-structures/1-cursor/g-4140.md @@ -5,7 +5,7 @@ ## Reason -Oracle provides a variety of cursor attributes (like `%found` and `%rowcount`) that can be used to obtain information about the status of a cursor, either implicit or explicit. +The Oracle Database provides a variety of cursor attributes (like `%found` and `%rowcount`) that can be used to obtain information about the status of a cursor, either implicit or explicit. You should avoid inserting any statements between the cursor operation and the use of an attribute against that cursor. Interposing such a statement can affect the value returned by the attribute, thereby potentially corrupting the logic of your program. diff --git a/docs/4-language-usage/4-control-structures/2-case-if-decode-nvl-nvl2-coalesce/g-4220.md b/docs/4-language-usage/4-control-structures/2-case-if-decode-nvl-nvl2-coalesce/g-4220.md index e49f5232..11940b22 100644 --- a/docs/4-language-usage/4-control-structures/2-case-if-decode-nvl-nvl2-coalesce/g-4220.md +++ b/docs/4-language-usage/4-control-structures/2-case-if-decode-nvl-nvl2-coalesce/g-4220.md @@ -5,7 +5,7 @@ ## Reason -`decode` is an Oracle specific function hard to understand and restricted to SQL only. The “newer” `case` function is much more common, has a better readability and may be used within PL/SQL too. Be careful that `decode` can handle `null` values, which the simple `case` cannot - for such cases you must use the searched `case` and `is null` instead. +`decode` is an Oracle Database specific function hard to understand and restricted to SQL only. The “newer” `case` function is much more common, has a better readability and may be used within PL/SQL too. Be careful that `decode` can handle `null` values, which the simple `case` cannot - for such cases you must use the searched `case` and `is null` instead. ## Example (bad) diff --git a/docs/4-language-usage/5-exception-handling/g-5010.md b/docs/4-language-usage/5-exception-handling/g-5010.md index 487ef9e2..f0a1dcf0 100644 --- a/docs/4-language-usage/5-exception-handling/g-5010.md +++ b/docs/4-language-usage/5-exception-handling/g-5010.md @@ -15,7 +15,7 @@ This kind of framework should include * Logging (different channels like table, mail, file, etc. if needed) * Error Raising * Multilanguage support if needed -* Translate Oracle error messages to a user friendly error text +* Translate Oracle Database error messages to a user friendly error text * Error repository ## Example (bad) diff --git a/docs/4-language-usage/5-exception-handling/g-5030.md b/docs/4-language-usage/5-exception-handling/g-5030.md index df6bd095..567af0a9 100644 --- a/docs/4-language-usage/5-exception-handling/g-5030.md +++ b/docs/4-language-usage/5-exception-handling/g-5030.md @@ -5,7 +5,7 @@ ## Reason -This is error-prone because your local declaration overrides the global declaration. While it is technically possible to use the same names, it causes confusion for others needing to read and maintain this code. Additionally, you will need to be very careful to use the prefix `standard` in front of any reference that needs to use Oracle’s default exception behavior. +This is error-prone because your local declaration overrides the global declaration. While it is technically possible to use the same names, it causes confusion for others needing to read and maintain this code. Additionally, you will need to be very careful to use the prefix `standard` in front of any reference that needs to use the default exception behavior of the Oracle Database. ## Example (bad) diff --git a/docs/4-language-usage/5-exception-handling/g-5050.md b/docs/4-language-usage/5-exception-handling/g-5050.md index 18aec6b5..e3a07455 100644 --- a/docs/4-language-usage/5-exception-handling/g-5050.md +++ b/docs/4-language-usage/5-exception-handling/g-5050.md @@ -5,7 +5,7 @@ ## Reason -If you are not very organized in the way you allocate, define and use the error numbers between 20999 and 20000 (those reserved by Oracle for its user community), it is very easy to end up with conflicting usages. You should assign these error numbers to named constants and consolidate all definitions within a single package. When you call `raise_application_error`, you should reference these named elements and error message text stored in a table. Use your own raise procedure in place of explicit calls to `raise_application_error`. If you are raising a "system" exception like `no_data_found`, you must use `raise`. However, when you want to raise an application-specific error, you use `raise_application_error`. If you use the latter, you then have to provide an error number and message. This leads to unnecessary and damaging hard-coded values. A more fail-safe approach is to provide a predefined raise procedure that automatically checks the error number and determines the correct way to raise the error. +If you are not very organized in the way you allocate, define and use the error numbers between 20999 and 20000 (those reserved by the Oracle Database for its user community), it is very easy to end up with conflicting usages. You should assign these error numbers to named constants and consolidate all definitions within a single package. When you call `raise_application_error`, you should reference these named elements and error message text stored in a table. Use your own raise procedure in place of explicit calls to `raise_application_error`. If you are raising a "system" exception like `no_data_found`, you must use `raise`. However, when you want to raise an application-specific error, you use `raise_application_error`. If you use the latter, you then have to provide an error number and message. This leads to unnecessary and damaging hard-coded values. A more fail-safe approach is to provide a predefined raise procedure that automatically checks the error number and determines the correct way to raise the error. ## Example (bad) diff --git a/docs/4-language-usage/7-stored-objects/5-oracle-supplied-packages/g-7510.md b/docs/4-language-usage/7-stored-objects/5-oracle-supplied-packages/g-7510.md index ede50eca..2be0b0d7 100644 --- a/docs/4-language-usage/7-stored-objects/5-oracle-supplied-packages/g-7510.md +++ b/docs/4-language-usage/7-stored-objects/5-oracle-supplied-packages/g-7510.md @@ -5,7 +5,7 @@ ## Reason -The signature of Oracle-supplied packages is well known and therefore it is quite easy to provide packages with the same name as those from Oracle doing something completely different without you noticing it. +The signature of Oracle supplied packages is well known and therefore it is quite easy to provide packages with the same name as those from Oracle doing something completely different without you noticing it. ## Example (bad) diff --git a/docs/4-language-usage/7-stored-objects/8-sequences/g-7810.md b/docs/4-language-usage/7-stored-objects/8-sequences/g-7810.md index fe8ec3eb..0093b919 100644 --- a/docs/4-language-usage/7-stored-objects/8-sequences/g-7810.md +++ b/docs/4-language-usage/7-stored-objects/8-sequences/g-7810.md @@ -5,7 +5,7 @@ ## Reason -Since Oracle 11g it is no longer needed to use a `select` statement to read a sequence (which would imply a context switch). +Since Oracle Database 11g it is no longer needed to use a `select` statement to read a sequence (which would imply a context switch). ## Example (bad) diff --git a/docs/7-tool-support/1-db-codecop-sqldev.md b/docs/7-tool-support/1-db-codecop-sqldev.md index 12842093..84b60f1b 100644 --- a/docs/7-tool-support/1-db-codecop-sqldev.md +++ b/docs/7-tool-support/1-db-codecop-sqldev.md @@ -20,7 +20,7 @@ The results are presented in an additional tabbed panel. One tab shows all guide ## Examples -Open an Oracle PL/SQL or SQL script in a SQL Developer editor and press Ctrl-Shift-C to check your code against the Trivadis PL/SQL & SQL guidelines. +Open a PL/SQL or SQL script in a SQL Developer editor and press Ctrl-Shift-C to check your code against the Trivadis PL/SQL & SQL guidelines. ![Check](../images/tvdcc-sqldev-check.png) diff --git a/docs/9-appendix/appendix.md b/docs/9-appendix/appendix.md index f61d0080..f9a0ed77 100644 --- a/docs/9-appendix/appendix.md +++ b/docs/9-appendix/appendix.md @@ -49,7 +49,7 @@ n/a | 3115 | Avoid self-assigning a column. | Minor | | | ✘ | | | | 27 | 3120 | Always use table aliases when your SQL statement involves more than one source. | Major | | | ✘ | | | | | 28 | 3130 | Try to use ANSI SQL-92 join syntax. | Minor | | | ✘ | ✘ | | | | 29 | 3140 | Try to use anchored records as targets for your cursors. | Major | | | ✘ | | ✘ | | | -n/a | 3145 | Avoid using SELECT \* directly from a table or view. | Major | | ✘ | ✘ | | ✘ | | | ✘ +n/a | 3145 | Avoid using SELECT * directly from a table or view. | Major | | ✘ | ✘ | | ✘ | | | ✘ n/a | 3150 | Try to use identity columns for surrogate keys. | Minor | | | ✘ | | ✘ | | | n/a | 3160 | Avoid visible virtual columns. | Major | | | ✘ | | ✘ | | | n/a | 3170 | Always use DEFAULT ON NULL declarations to assign default values to table columns if you refuse to store NULL values. | Major | | | | | ✘ | | |