Fix #81 - Removed G-7240 and replaced with G-7160 and G-7170

Author: kibeha

docs/4-language-usage/7-stored-objects/1-general/g-7160.md

@@ -0,0 +1,36 @@
+# G-7160: Always explicitly state parameter mode.
+
+!!! warning "Major"
+    Maintainability
+
+## Reason
+
+By showing the mode of parameters, you help the reader. If you do not specify a parameter mode, the default mode is `IN`. Explicitly showing the mode indication of all parameters is a more assertive action than simply taking the default mode. Anyone reviewing the code later will be more confident that you intended the parameter mode to be `IN`, `OUT` or `IN OUT`.
+
+## Example (bad)
+
+```
+CREATE OR REPLACE PACKAGE employee_api IS
+   PROCEDURE upsert (io_id             IN OUT employees.id%TYPE
+                    ,in_first_name            employees.first_name%TYPE
+                    ,in_last_name             employees.last_name%TYPE 
+                    ,in_email                 employees.email%TYPE 
+                    ,in_department_id         employees.department_id%TYPE
+                    ,out_success       OUT    PLS_INTEGER);
+END employee_up;
+/
+```
+
+## Example (good)
+
+```
+CREATE OR REPLACE PACKAGE employee_api IS
+   PROCEDURE upsert (io_id             IN OUT employees.id%TYPE
+                    ,in_first_name     IN     employees.first_name%TYPE
+                    ,in_last_name      IN     employees.last_name%TYPE 
+                    ,in_email          IN     employees.email%TYPE 
+                    ,in_department_id  IN     employees.department_id%TYPE
+                    ,out_success       OUT    PLS_INTEGER);
+END employee_up;
+/
+```

docs/4-language-usage/7-stored-objects/2-packages/g-7240.md renamed to docs/4-language-usage/7-stored-objects/1-general/g-7170.md

@@ -1,16 +1,18 @@
-# G-7240: Avoid using an IN OUT parameter as IN or OUT only.
+# G-7170: Avoid using an IN OUT parameter as IN or OUT only.
 
 !!! warning "Major"
     Efficiency, Maintainability
 
+!!! missing "Unsupported in PL/SQL Cop Validators"
+    Rule G-7170 is not expected to be implemented in the static code analysis validators.
+
 ## Reason
 
-By showing the mode of parameters, you help the reader. If you do not specify a parameter mode, the default mode is `IN`. Explicitly showing the mode indication of all parameters is a more assertive action than simply taking the default mode. Anyone reviewing the code later will be more confident that you intended the parameter mode to be `IN` / `OUT`.
+Avoid using parameter mode `IN OUT` unless you actually use the parameter both as input and output. If the code body only reads from the parameter, use `IN`; if the code body only assigns to the parameter, use `OUT`. If at the beginning of a project you expect a parameter to be both input and output and therefore choose `IN OUT` just in case, but later development shows the parameter actually is only `IN` or `OUT`, you should change the parameter mode accordingly.
 
 ## Example (bad)
 
 ```
--- Bad
 CREATE OR REPLACE PACKAGE BODY employee_up IS
    PROCEDURE rcv_emp (io_first_name     IN OUT employees.first_name%TYPE
                      ,io_last_name      IN OUT employees.last_name%TYPE 
@@ -22,7 +24,7 @@ CREATE OR REPLACE PACKAGE BODY employee_up IS
                      ,io_commission_pct IN OUT employees.commission_pct%TYPE 
                      ,io_manager_id     IN OUT employees.manager_id%TYPE
                      ,io_department_id  IN OUT employees.department_id%TYPE
-                     ,in_wait                  INTEGER) IS
+                     ,in_wait           IN     INTEGER) IS
       l_status PLS_INTEGER;
       co_dflt_pipe_name CONSTANT STRING(30 CHAR) := 'MyPipe';
       co_ok CONSTANT PLS_INTEGER := 1;
@@ -51,17 +53,17 @@ END employee_up;
 
 ```
 CREATE OR REPLACE PACKAGE BODY employee_up IS
-   PROCEDURE rcv_emp (OUT_first_name     OUT employees.first_name%TYPE
-                     ,OUT_last_name      OUT employees.last_name%TYPE 
-                     ,OUT_email          OUT employees.email%TYPE 
-                     ,OUT_phone_number   OUT employees.phone_number%TYPE
-                     ,OUT_hire_date      OUT employees.hire_date%TYPE 
-                     ,OUT_job_id         OUT employees.job_id%TYPE
-                     ,OUT_salary         OUT employees.salary%TYPE
-                     ,OUT_commission_pct OUT employees.commission_pct%TYPE 
-                     ,OUT_manager_id     OUT employees.manager_id%TYPE
-                     ,OUT_department_id  OUT employees.department_id%TYPE
-                     ,in_wait            IN     INTEGER) IS
+   PROCEDURE rcv_emp (out_first_name     OUT employees.first_name%TYPE
+                     ,out_last_name      OUT employees.last_name%TYPE 
+                     ,out_email          OUT employees.email%TYPE 
+                     ,out_phone_number   OUT employees.phone_number%TYPE
+                     ,out_hire_date      OUT employees.hire_date%TYPE 
+                     ,out_job_id         OUT employees.job_id%TYPE
+                     ,out_salary         OUT employees.salary%TYPE
+                     ,out_commission_pct OUT employees.commission_pct%TYPE 
+                     ,out_manager_id     OUT employees.manager_id%TYPE
+                     ,out_department_id  OUT employees.department_id%TYPE
+                     ,in_wait            IN  INTEGER) IS
       l_status PLS_INTEGER;
       co_dflt_pipe_name CONSTANT STRING(30 CHAR) := 'MyPipe';
       co_ok CONSTANT PLS_INTEGER := 1;