Fix Trivadis#57 - Altered rule to all lowercase. Added footnote on re…

…ason and importance of consistency. Converted all code examples to lowercase (thanks Philipp for https://www.salvis.com/blog/2020/08/28/formatting-sql-code-blocks-in-markdown-files/ )

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

@@ -6,8 +6,8 @@
 
 Rule | Description
 :--: | -----------
-1    | Keywords are written uppercase, names are written in lowercase.
-2    | 3 space indention[^2].
+1    | Keywords and names are written in lowercase[^2].
+2    | 3 space indention[^3].
 3    | One command per line.
 4    | Keywords `LOOP`, `ELSE`, `ELSIF`, `END IF`, `WHEN` on a new line.
 5    | Commas in front of separated elements.
@@ -19,33 +19,33 @@ Rule | Description
 ### Example
 
 ``` sql
-PROCEDURE set_salary(in_employee_id IN employees.employee_id%TYPE) IS
-   CURSOR c_employees(p_employee_id IN employees.employee_id%TYPE) IS 
-      SELECT last_name
+procedure set_salary(in_employee_id in employees.employee_id%type) is
+   cursor c_employees(p_employee_id in employees.employee_id%type) is 
+      select last_name
             ,first_name
             ,salary
-        FROM employees
-       WHERE employee_id = p_employee_id
-       ORDER BY last_name
+        from employees
+       where employee_id = p_employee_id
+       order by last_name
                ,first_name;
 
-   r_employee     c_employees%ROWTYPE;
-   l_new_salary   employees.salary%TYPE;
-BEGIN
-   OPEN  c_employees(p_employee_id => in_employee_id);
-   FETCH c_employees INTO r_employee;
-   CLOSE c_employees;
+   r_employee     c_employees%rowtype;
+   l_new_salary   employees.salary%type;
+begin
+   open  c_employees(p_employee_id => in_employee_id);
+   fetch c_employees into r_employee;
+   close c_employees;
 
    new_salary (in_employee_id => in_employee_id
               ,out_salary     => l_new_salary);
 
    -- Check whether salary has changed
-   IF r_employee.salary <> l_new_salary THEN
-      UPDATE employees
-         SET salary = l_new_salary
-       WHERE employee_id = in_employee_id;
-   END IF;
-END set_salary;
+   if r_employee.salary <> l_new_salary then
+      update employees
+         set salary = l_new_salary
+       where employee_id = in_employee_id;
+   end if;
+end set_salary;
 ```
 
 ## Code Commenting
@@ -80,15 +80,21 @@ Check whether we passed a valid sql name
 
 <b>Call Example:</b>
 <pre>
-   SELECT TVDAssert.valid_sql_name('TEST') from dual;
-   SELECT TVDAssert.valid_sql_name('123') from dual
+   select TVDAssert.valid_sql_name('TEST') from dual;
+   select TVDAssert.valid_sql_name('123') from dual
 </pre>
 */
 ```
 
 [^2]: 
+    It used to be good practice to use uppercase keywords and lowercase names to help visualize code structure. 
+    But practically all editors support more or less advanced color highlighting of code, similar to the examples in these guidelines. 
+    Hence as of version 4.0 we are now recommending all lowercase, as this is easier and faster for the brain to process. 
+    You may choose to prefer the old rule - however, it is important to always be consistent, like for example keywords always in uppercase and names always in lowercase.
+
+[^3]: 
     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. 
+    We want to ensure that the code looks the same, independent 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. 

docs/4-language-usage/1-general/g-1010.md

@@ -10,31 +10,31 @@ It's a good alternative for comments to indicate the start and end of a named pr
 ## Example (bad)
 
 ``` sql
-BEGIN
-   BEGIN 
-      NULL;
-   END;
-
-   BEGIN
-      NULL;
-   END;
-END;
+begin
+   begin 
+      null;
+   end;
+
+   begin
+      null;
+   end;
+end;
 /
 ```
 
 ## Example (good)
 
 ``` sql
-BEGIN
+begin
    <<prepare_data>>
-   BEGIN 
-      NULL;
-   END prepare_data;
+   begin 
+      null;
+   end prepare_data;
 
    <<process_data>>
-   BEGIN
-      NULL;
-   END process_data;
-END good;
+   begin
+      null;
+   end process_data;
+end good;
 /
 ```

docs/4-language-usage/1-general/g-1020.md

@@ -13,79 +13,79 @@ Use a label directly in front of loops and nested anonymous blocks:
 ## Example (bad)
 
 ``` sql
-DECLARE
-   i INTEGER;
-   co_min_value CONSTANT INTEGER := 1;
-   co_max_value CONSTANT INTEGER := 10;
-   co_increment CONSTANT INTEGER := 1;
-BEGIN
+declare
+   i integer;
+   co_min_value constant integer := 1;
+   co_max_value constant integer := 10;
+   co_increment constant integer := 1;
+begin
    <<prepare_data>>
-   BEGIN 
-      NULL;
-   END;
+   begin 
+      null;
+   end;
 
    <<process_data>>
-   BEGIN
-      NULL;
-   END;
+   begin
+      null;
+   end;
 
    i := co_min_value;
    <<while_loop>>
-   WHILE (i <= co_max_value) 
-   LOOP 
+   while (i <= co_max_value) 
+   loop 
       i := i + co_increment; 
-   END LOOP;
+   end loop;
 
    <<basic_loop>>
-   LOOP 
-      EXIT basic_loop;
-   END LOOP;
+   loop 
+      exit basic_loop;
+   end loop;
 
    <<for_loop>>
-   FOR i IN co_min_value..co_max_value
-   LOOP 
+   for i in co_min_value..co_max_value
+   loop 
       sys.dbms_output.put_line(i);
-   END LOOP;
-END;
+   end loop;
+end;
 /
 ```
 
 ## Example (good)
 
 ``` sql
-DECLARE
-   i INTEGER;
-   co_min_value CONSTANT INTEGER := 1;
-   co_max_value CONSTANT INTEGER := 10;
-   co_increment CONSTANT INTEGER := 1;
-BEGIN
+declare
+   i integer;
+   co_min_value constant integer := 1;
+   co_max_value constant integer := 10;
+   co_increment constant integer := 1;
+begin
    <<prepare_data>>
-   BEGIN 
-      NULL;
-   END prepare_data;
+   begin 
+      null;
+   end prepare_data;
 
    <<process_data>>
-   BEGIN
-      NULL;
-   END process_data;
+   begin
+      null;
+   end process_data;
 
    i := co_min_value;
    <<while_loop>>
-   WHILE (i <= co_max_value) 
-   LOOP 
+   while (i <= co_max_value) 
+   loop 
       i := i + co_increment; 
-   END LOOP while_loop;
+   end loop while_loop;
 
    <<basic_loop>>
-   LOOP 
-      EXIT basic_loop;
-   END LOOP basic_loop;
+   loop 
+      exit basic_loop;
+   end loop basic_loop;
 
    <<for_loop>>
-   FOR i IN co_min_value..co_max_value
-   LOOP 
+   for i in co_min_value..co_max_value
+   loop 
      sys.dbms_output.put_line(i);
-   END LOOP for_loop;
-END;
+   end loop for_loop;
+end;
 /
 ```

docs/4-language-usage/1-general/g-1030.md

@@ -10,44 +10,44 @@ Unused variables decrease the maintainability and readability of your code.
 ## Example (bad)
 
 ``` sql
-CREATE OR REPLACE PACKAGE BODY my_package IS
-   PROCEDURE my_proc IS
-      l_last_name  employees.last_name%TYPE;
-      l_first_name employees.first_name%TYPE;
-      co_department_id CONSTANT departments.department_id%TYPE := 10;
-      e_good EXCEPTION;
-   BEGIN
-      SELECT e.last_name
-        INTO l_last_name
-        FROM employees e
-       WHERE e.department_id = co_department_id;
-   EXCEPTION
-      WHEN no_data_found THEN NULL; -- handle_no_data_found;
-      WHEN too_many_rows THEN null; -- handle_too_many_rows;
-   END my_proc;
-END my_package;
+create or replace package body my_package is
+   procedure my_proc is
+      l_last_name  employees.last_name%type;
+      l_first_name employees.first_name%type;
+      co_department_id constant departments.department_id%type := 10;
+      e_good exception;
+   begin
+      select e.last_name
+        into l_last_name
+        from employees e
+       where e.department_id = co_department_id;
+   exception
+      when no_data_found then null; -- handle_no_data_found;
+      when too_many_rows then null; -- handle_too_many_rows;
+   end my_proc;
+end my_package;
 /
 ```
 
 ## Example (good)
 
 ``` sql
-CREATE OR REPLACE PACKAGE BODY my_package IS
-   PROCEDURE my_proc IS
-      l_last_name  employees.last_name%TYPE;
-      co_department_id CONSTANT departments.department_id%TYPE := 10;
-      e_good EXCEPTION;
-   BEGIN
-      SELECT e.last_name
-        INTO l_last_name
-        FROM employees e
-       WHERE e.department_id = co_department_id;
-
-      RAISE e_good;
-   EXCEPTION
-      WHEN no_data_found THEN NULL; -- handle_no_data_found;
-      WHEN too_many_rows THEN null; -- handle_too_many_rows;
-   END my_proc;
-END my_package;
+create or replace package body my_package is
+   procedure my_proc is
+      l_last_name  employees.last_name%type;
+      co_department_id constant departments.department_id%type := 10;
+      e_good exception;
+   begin
+      select e.last_name
+        into l_last_name
+        from employees e
+       where e.department_id = co_department_id;
+
+      raise e_good;
+   exception
+      when no_data_found then null; -- handle_no_data_found;
+      when too_many_rows then null; -- handle_too_many_rows;
+   end my_proc;
+end my_package;
 /
 ```