Merge pull request #307 from SAP/full_documentation_review

Full documentation review

Author: lucasborin

docs/checks/boolean-input-parameter.md

@@ -1,22 +1,20 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Boolean Input Parameter](boolean-input-parameter.md)
 
 ## Boolean Input Parameter
 
 ### What is the Intent of the Check?
 
-Usage of boolean input parameters because they are often an indicator that a method does two things instead of one.  
-Ps: Setter methods using boolean variables are ok.
+This check searches for the usage of boolean input parameters in a method signature. These parameters, could be an indicator of bad design where the Single Responsibility Principle is not followed (the method might be doing several things instead of a single thing).   
+
+REMARK: Setter methods using boolean input variables are acceptable.
 
 ### How to solve the issue?
 
-Splitting the method may simplify the methods' code and describe the different intentions better.
+Splitting the method may simplify its code and provide a better description for the consumer.
 
 ### What to do in case of exception?
 
-You can suppress Code Inspector findings generated by this check using the pseudo comment `"#EC BOOL_PARAM`.  
-The pseudo comment has to be placed after the method declaration.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC BOOL_PARAM` which has to be placed after the method declaration:
 
 ```abap
   METHODS update IMPORTING do_save TYPE abap_bool. "#EC BOOL_PARAM
@@ -34,9 +32,9 @@ After the check:
 
 ```abap
   METHODS update_without_saving.
-  METHODS update_and_save.
+  METHODS update_and_commit.
 ```
 
 ### Further Readings & Knowledge
 
-* [ABAP Styleguides on Clean Code](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#split-method-instead-of-boolean-input-parameter)
+* [ABAP Styleguides on Clean Code: Boolean Input Parameter(s)](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#split-method-instead-of-boolean-input-parameter)

docs/checks/call-method-usage.md

@@ -1,28 +1,22 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [CALL METHOD Usage Check](call-method-usage.md)
 
 ## CALL METHOD Usage Check
 
 ### What is the Intent of the Check?
 
-The "CALL METHOD Usage" check verifies the usage of the `CALL METHOD` ABAP statement. It is preferable not to call a method via this statement: CALL METHOD. Since it is preferable functional instead of procedural calls.
+This check verifies the usage of the `CALL METHOD` ABAP statement. It is preferable to call a method dynamically instead of via this statement: CALL METHOD. In other words, prefer a functional instead of a procedural call.
 
 ### How does the check work?
 
-It simply checks if the code is using the `CALL METHOD` statement.
-
-### Which attributes can be maintained?
-
-![Attributes](./imgs/call_method_usage.png)
+It checks the usage of `CALL METHOD` statement in the code.
 
 ### How to solve the issue?
 
-Change the long method calls using `CALL METHOD` statement to short method calls using parenthesis notation.
+Change the long method calls using `CALL METHOD` statement to short method calls using parenthesis notation (dynamic call).
 
 ### What to do in case of exception?
 
-You can suppress Code Inspector findings generated by this check using the pseudo comment `"#EC CALL_METH_USAGE`. The pseudo comment has to be placed after the `CALL METHOD` statement.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC CALL_METH_USAGE` which has to be placed after the `CALL METHOD` statement:
 
 ```abap
 CALL METHOD method_name. "#EC CALL_METH_USAGE
@@ -46,4 +40,4 @@ class->method( ).
 
 ### Further Readings & Knowledge
 
-* [ABAP Styleguides on Clean Code](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#prefer-functional-to-procedural-calls)
+* [ABAP Styleguides on Clean Code: Avoid CALL METHOD Statement](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#prefer-functional-to-procedural-calls)

docs/checks/chain-declaration-usage.md

@@ -1,21 +1,18 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Chain Declaration Usage](chain-declaration-usage.md)
 
 ## Chain Declaration Usage
 
 ### What is the Intent of the Check?
 
-The "Chain Declaration Usage" check verifies the usage of the chain up-front declarations.
+This check verifies the usage of chain up-front declarations.
 
 ### How to solve the issue?
 
 Change the chain up-front declarations to inline declarations.
 
 ### What to do in case of exception?
 
-You can suppress Code Inspector findings generated by this check using the pseudo comment `"#EC CHAIN_DECL_USAG`.  
-The pseudo comment has to be placed after the `DATA:` statement.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC CHAIN_DECL_USAG` which should be placed after the `DATA:` statement:
 
 ```abap
   DATA: "#EC CHAIN_DECL_USAG
@@ -43,6 +40,15 @@ After the check:
   DATA client LIKE sy-mandt.
 ```
 
+Or even (which looks neat - but it won't be enforced):
+
+```abap
+DATA var1         TYPE a.
+DATA var2         TYPE string.
+DATA my_var3      TYPE int.
+DATA a            TYPE c.
+```
+
 ### Further Readings & Knowledge
 
-* [ABAP Styleguides on Clean Code](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#do-not-chain-up-front-declarations)
+* [ABAP Styleguides on Clean Code: Do not chain up-front declarations](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#do-not-chain-up-front-declarations)

docs/checks/check-in-loop.md

@@ -1,18 +1,16 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [CHECK in LOOP](check-in-loop.md)
 
 ## CHECK in LOOP
 
 ### What is the Intent of the Check?
-It verifies whether the `CHECK` statement is found inside of a `LOOP` statement. A CHECK within a LOOP, ends the current iteration and proceeds to the next one. This behaviour might lead to confusion: Does it end the method processing or does it exit the loop?
+This check verifies if a `CHECK` statement is being used inside of a `LOOP` structure. A CHECK within a LOOP, ends the current iteration and proceeds to the next one. This behaviour might lead to some confusion like: Does it end the method processing or does it exit the loop?
 
 ### How to solve the issue?
-Prefer using `CONTINUE` within an IF-Statement instead (since the keyword `CONTINUE` can only be used in loops, the intention is clear to everyone reading the code).
-Keep also in mind, the other Keywords like `EXIT` and `RETURN` are also more explicit.
+Prefer using `CONTINUE` (within an IF-Statement) instead of using the CHECK Statement in this case. Since the keyword `CONTINUE` can only be used in LOOPS, the intention is then automatic clear to everyone reading the code.
+Keep also in mind, that other Keywords like: `EXIT` or `RETURN` are also more explicit than `CHECK`.
 
 ### What to do in case of exception?
-In special cases you can suppress this finding by using the pseudo comment `"#EC CHECK_IN_LOOP`.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC CHECK_IN_LOOP` which should be placed after the `CHECK` Statement itself:
 
 ```abap
 LOOP AT tadir ASSIGNING FIELD-SYMBOL(<tadir>).
@@ -38,5 +36,5 @@ ENDLOOP.
 ```
 
 ### Further Readings & Knowledge
-- [Avoid CHECK in other positions (Clean ABAP)](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#avoid-check-in-other-positions)
+- [ABAP Stylegruides on Clean Code: Avoid CHECK in other positions](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#avoid-check-in-other-positions)
 - [Exiting Loops -> Check](https://help.sap.com/doc/abapdocu_752_index_htm/7.52/en-US/abapcheck_loop.htm)

docs/checks/check-statement-position.md

@@ -1,20 +1,29 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [CHECK Statement Position Check](check-statement-position.md)
 
 ## CHECK Statement Position Check
 
 ### What is the Intent of the Check?
-It verifies whether the `CHECK` statement is the first statement within a method, function-module, or form-routine.  
+This check verifies whether the `CHECK` statement is the very first statement within a method, function-module or form-routine.  
 
 The [Clean ABAP](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#avoid-check-in-other-positions) says:
 > Do not use `CHECK` outside of the initialization section of a method. The statement behaves differently in different positions and may lead to unclear, unexpected effects.
 
+REMARKS: 
+1. CHECK statement inside of LOOPs will be disregard by check (for that, refer to: CHECK_IN_LOOP). 
+2. The usage of CLEAR statement prior to CHECK statement is considered to be a bad coding practice! This is actually a workaround in bad designed code (against OO scope principles). 
+3. DATA declarations (DATA / FIELD-SYMBOLS when not dynamic declared – inline declarations), might also come before the keyword CHECK.
+
 ### How to solve the issue?
 The `CHECK` statement shall be the first statement of a method. If it is not possible, try to substitute this keyword with an IF-statement instead.
 
 ### What to do in case of exception?
-In special cases you can suppress this finding by using the pseudo comment `"#EC CHECK_POSITION`.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC CHECK_POSITION` which has to be placed after the `CHECK` statement:
+
+```abap
+METHOD example.
+  some code...
+  CHECK condition = abap_true. "#EC CHECK_POSITION
+```
 
 ### Example
 Before the check:
@@ -36,6 +45,8 @@ METHOD example.
   ...
 ENDMETHOD.
 ```
+OR
+
 ```abap
 METHOD example.
   CHECK sy-mandt = 000.
@@ -44,4 +55,4 @@ ENDMETHOD.
 ``` 
 
 ### Further Readings & Knowledge
-- [Avoid CHECK in other positions (Clean ABAP)](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#avoid-check-in-other-positions)
+- [ABAP Styleguides on Clean Code: Avoid CHECK in other positions (Clean ABAP)](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#avoid-check-in-other-positions)

docs/checks/comment-position.md

@@ -1,16 +1,14 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Comment Position](comment-position.md)
 
 ## Comment Position
 
 ### What is the Intent of the Check?
 
-Quote comments indent along with the statements they comment.
+This check searches for "Quote comments" which are not indented along with the statements they belong to.
 
 ### How to solve the issue?
 
-Identing the comments along with the statements.
+You should indent the comments along with the statements they are commenting.
 
 ### Example
 

docs/checks/comment-type.md

@@ -1,16 +1,14 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Comment Type](comment-type.md)
 
 ## Comment Type
 
 ### What is the Intent of the Check?
 
-Comments with `"`, not with `*`, because asterisked comments tend to indent to weird places.
+This check searches for comments in the code marked up with `"` instead of with `*`. Comments marked up with an asterisk tend to be indented to weird/uncontrolled places.
 
 ### How to solve the issue?
 
-Replacing the comment type from `*` to `"`.
+You should replace the comment sign from `*` to `"`.
 
 ### Example
 
@@ -38,4 +36,4 @@ After the check:
 
 ### Further Readings & Knowledge
 
-* [ABAP Styleguides on Clean Code](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#comment-with--not-with-)
+* [ABAP Styleguides on Clean Code: Comment sign](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#comment-with--not-with-)

docs/checks/comment-usage.md

@@ -1,29 +1,23 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Comment Usage Check](comment-usage.md)
 
 ## Comment Usage Check
 
 ### What is the Intent of the Check?
 
-The “Comment Usage” Check is part of the Clean Code Check Repository. Express yourself in code, not in comments. Clean Code does not forbid you to comment your code - it encourages you to exploit better means, and resort to comments only if that fails.
+This check searches for comments in the code. Clean Code principles do not forbid you to comment your code - but it encourages you to exploit better means, meaningful names and resort to comments only if that fails. Express yourself in code, not in comments.
 
 ### How does the check work?
 
-This check calculates the percentage of comments in relation to the absolute number of statements (productive code).
-
-### Which attributes can be maintained?
-
-![Attributes](./imgs/comment_usage.png)
+This check calculates an indicator; precisely, the percentage of comments in relation to the absolute number of real statements (productive code).
 
 ### How to solve the issue?
 
-Remove unimportant comments.
+Remove unimportant and/or unnecessary comments.
 
 ### What to do in case of exception?
 
-There should be no exception as the check works as an indication. Thus, it is also not possible to suppress Code Inspector findings from this check.
+There is no exception for this check since it works as an indicator only. Thus, it is also not possible to suppress its findings.
 
 ### Further Readings & Knowledge
 
-* [ABAP Styleguides on Clean Code](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#express-yourself-in-code-not-in-comments)
+* [ABAP Styleguides on Clean Code: Less is more](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#express-yourself-in-code-not-in-comments)

docs/checks/constants-interface.md

@@ -1,12 +1,10 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [Constants Interface Check](constants-interface.md)
 
 ## Constants Interface Check
 
 ### What is the Intent of the Check?
 
-To avoid the creation and usage of an interface object for merely definying contants.
+This check intends to avoid the creation and usage of an interface object for merely definying contants.
 You should always prefer [enumeration classes](https://github.com/SAP/styleguides/blob/master/clean-abap/CleanABAP.md#prefer-enumeration-classes-to-constants-interfaces) to constants interfaces.
 
 ```abap
@@ -34,18 +32,13 @@ ENDCLASS.
 
 The "Constant Interface" check searches for interfaces containing only constants.
 
-### Which attributes can be maintained?
-
-![Attributes](./imgs/constants_interface.png)
-
 ### How to solve the issue?
 
 Use enumeration classes instead.
 
 ### What to do in case of exception?
 
-In special cases, it is possible to suppress a finding by using the pseudo comment `"#EC CONS_INTF`.  
-The pseudo comment must be placed right after the class definition header.
+In exceptional cases, you can suppress this finding by using the pseudo comment `"#EC CONS_INTF` which should be placed right after the class definition header:
 
 ### Example
 

docs/checks/cx-root-usage.md

@@ -1,12 +1,10 @@
-# code pal for ABAP
-
 [code pal for ABAP](../../README.md) > [Documentation](../check_documentation.md) > [CX_ROOT Usage Check](cx-root-usage.md)
 
 ## CX_ROOT Usage Check
 
 ### What is the Intent of the Check?
 
-The “CX_ROOT Usage" Check searches for merely "CX_ROOT" exceptions being directly used in the code (e.g.: In a TRY-CATCH block). 
+This check searches for direct "CX_ROOT" exceptions being used in the code (e.g.: In a TRY-CATCH block). 
 
 ### How does the check work?
 
@@ -27,17 +25,13 @@ CLASS cx_my_exception DEFINITION INHERITING FROM cx_root.
 ENDCLASS.
 ```
 
-### Which attributes can be maintained?
-
-![Attributes](./imgs/cx_root_usage.png)
-
 ### How to solve the issue?
 
 The solution is to use well defined and specific class-based exceptions.
 
 ### What to do in case of exception?
 
-In special cases you can suppress this Check’s finding by using the pseudo comment `“#EC NEED_CX_ROOT`.
+In exceptional cases, you can suppress this finding by using the pseudo comment `“#EC NEED_CX_ROOT` which should be placed after the CATCH statement: 
 
 ```abap
 TRY.