Merge pull request #59 from Trivadis/56-plural-singular

Fixes #56 - plural vs. singular table/view names

Author: PhilippSalvisberg

PLSQL-and-SQL-Coding-Guidelines.pdf

@@ -64,5 +64,24 @@ Implementing formatting and coding standards has the following advantages for PL
 * 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](../4-language-usage/2-variables-and-types/1-general/g-2150): Avoid comparisons with NULL value, consider using IS [NOT] NULL.
+
+2. Controversial
+
+    Almost every rule/guildeline falls into this category. An example of this category is [3 space indention](../3-coding-style/coding-style/#rules). - 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](https://github.com/Trivadis/plsql-and-sql-coding-guidelines) and amend the standards fit your needs/expectations.

docs/1-introduction/introduction.md

@@ -56,7 +56,7 @@ Examples:
 
 ### Column
 
-Singular name of what is stored in the column (unless the column data type is a collection, in this case you use plural names)
+Singular name of what is stored in the column (unless the column data type is a collection, in this case you use plural[^1] names)
 
 Add a comment to the database dictionary for every column.
 
@@ -182,7 +182,7 @@ Examples:
 
 ### Table
 
-Plural name of what is contained in the table (unless the table is designed to always hold one row only – then you should use a singular name)
+Plural[^1] name of what is contained in the table (unless the table is designed to always hold one row only – then you should use a singular name)
 
 Add a comment to the database dictionary for every table and every column in the table.
 
@@ -223,7 +223,7 @@ Examples:
 
 ### View
 
-Plural name of what is contained in the view.
+Plural[^1] name of what is contained in the view.
 Optionally suffixed by an indicator identifying the object as a view (mostly used, when a 1:1 view layer lies above the table layer)
 
 Add a comment to the database dictionary for every view and every column.
@@ -234,3 +234,11 @@ Examples:
 
 * `active_orders`
 * `orders_v` - a view to the orders table
+
+[^1]:
+    We see a table and a views as a collection. A jar containing beans is labeled with "beans". 
+    In Java we call such collection also beans (`List<Bean> 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 
+    the same concept for their tables and views lead to the decision to use the plural 
+    to name a table or view.

docs/2-naming-conventions/naming-conventions.md

@@ -7,7 +7,7 @@
 Rule | Description
 :--: | -----------
 1    | Keywords are written uppercase, names are written in lowercase.
-2    | 3 space indention.
+2    | 3 space indention[^2].
 3    | One command per line.
 4    | Keywords `LOOP`, `ELSE`, `ELSIF`, `END IF`, `WHEN` on a new line.
 5    | Commas in front of separated elements.
@@ -85,3 +85,13 @@ Check whether we passed a valid sql name
 </pre>
 */
 ```
+
+[^2]: 
+    Tabs are not used because the indentation depends on the editor configuration. 
+    We want to ensure that the code looks the same, indepenent of the editor used. 
+    Hence, no tabs. But why not use 8 spaces? That's the traditional value for a tab. 
+    When writing a package function the code in the body has an indentation of 3. 
+    That's 24 characters as a starting point for the code. We think it's too much. 
+    Especially if we try to keep a line below 100 or 80 characters. Other good options 
+    would be 2 or 4 spaces. We settled for 3 spaces as a compromise. 
+    The indentation is still good visible, but does not use to much space.

docs/3-coding-style/coding-style.md

@@ -36,6 +36,16 @@
         display: none;
     }
 
+    /* disable header of footnotes */
+    .footnote h1 {
+        display: none;
+    }
+
+    /* do not show link details in brackets content: " [" attr(href) "]" */
+    .md-typeset a:after {
+        display: none;
+    }
+
     /* disable scrollbar */
     .md-typeset__scrollwrap, 
     .md-typeset table:not([class]), 
@@ -65,6 +75,11 @@
         page-break-before: avoid;
     }
 
+    [id="we-do-not-agree-with-all-your-standards"],
+    [id="column"],
+    [id="sequence"],
+    [id="temporary-table-global-temporary-table"],
+    [id="code-commenting"],
     [id="variables-types"], 
     [id="numeric-data-types"], 
     [id="character-data-types"], 

docs/stylesheets/extra.css

@@ -23,6 +23,7 @@ extra_javascript:
 markdown_extensions:
   - admonition
   - pymdownx.arithmatex
+  - footnotes
 
 extra:
   guideline_version: 3.4-SNAPSHOT

mkdocs.yml

@@ -19,7 +19,15 @@ function create_cover() {
 function write_file(){
     FILE=$1
     echo "" >> ${TARGET_DIR}/docs/index.md
-    sed -e 's/..\/image/image/g' ${DATA_DIR}/docs/${FILE} | sed -e 's/✘/X/g' >> ${TARGET_DIR}/docs/index.md
+    sed -e 's/..\/image/image/g' ${DATA_DIR}/docs/${FILE} | \
+        sed -e 's|../4-language-usage/2-variables-and-types/1-general/g-2150|#g-2150-avoid-comparisons-with-null-value-consider-using-is-not-null|g' | \
+        sed -e 's|../3-coding-style/coding-style/#rules|#rules|g' | \
+        sed -e 's/✘/X/g' >> ${TARGET_DIR}/docs/index.md
+}
+
+function fix_footnote_links() {
+    mv index.html index.ori.html
+    sed -e 's/a class="footnote-ref"/a /g' index.ori.html > index.html
 }
 
 function write_text(){
@@ -47,6 +55,7 @@ function convert_to_pdf(){
     cd ${TARGET_DIR}
     mkdocs build
     cd site
+    fix_footnote_links
     wkhtmltopdf --javascript-delay 3000 \
                 --outline-depth 6 \
                 --outline \