abapgit-agent 1.15.1 → 1.15.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,28 +1,250 @@
1
1
  ---
2
2
  layout: default
3
3
  title: CDS Testing
4
- nav_order: 22
4
+ nav_order: 10
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
8
8
 
9
9
  # CDS Testing
10
10
 
11
- ### Use CDS Test Double Framework for CDS View Tests
11
+ **Searchable keywords**: CDS test double, CL_CDS_TEST_ENVIRONMENT, IF_CDS_TEST_ENVIRONMENT, insert_test_data, clear_doubles, create_for_multiple_cds, class_setup, class_teardown, aggregation test, CDS unit test
12
12
 
13
- **When creating unit tests for CDS views, use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`).**
13
+ ## TOPICS IN THIS FILE
14
+ 1. When to Use CDS Test Doubles - line 22
15
+ 2. Basic Setup Pattern - line 30
16
+ 3. Testing CDS Views with Aggregations - line 100
17
+ 4. Testing CDS Views that Select from Another CDS View - line 130
18
+ 5. Key Classes and Methods - line 170
19
+ 6. Important Usage Notes - line 190
20
+
21
+ ---
22
+
23
+ ## 1. When to Use CDS Test Doubles
14
24
 
15
25
  ```
16
26
  ❌ WRONG: Use regular AUnit test class without test doubles
17
27
  ✅ CORRECT: Use CL_CDS_TEST_ENVIRONMENT to create test doubles for CDS views
18
28
  ```
19
29
 
20
- **Why**: CDS views read from database tables. Using test doubles allows:
21
- - Injecting test data without affecting production data
22
- - Testing specific scenarios that may not exist in production
23
- - Fast, isolated tests that don't depend on database state
30
+ Use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`) whenever:
31
+ - A class under test calls `SELECT FROM <cds_view>` directly or via a helper
32
+ - You need controlled test data (not production data)
33
+ - You need to test CDS view logic with specific scenarios
34
+
35
+ **Why**: CDS views read from database tables. Using test doubles allows injecting test data
36
+ without affecting production data, and keeps tests fast and isolated.
37
+
38
+ ---
39
+
40
+ ## 2. Basic Setup Pattern
41
+
42
+ The test class lives in `<classname>.clas.testclasses.abap`. The CDS view itself has no
43
+ `.testclasses` file — test it through a regular ABAP class that reads it.
44
+
45
+ ```abap
46
+ "-------------------------
47
+ " CLASS DEFINITION
48
+ "-------------------------
49
+ CLASS ltcl_cds_test DEFINITION FOR TESTING RISK LEVEL HARMLESS DURATION SHORT FINAL.
50
+
51
+ PRIVATE SECTION.
52
+ " IMPORTANT: Use interface type, not class type!
53
+ DATA mo_cds_env TYPE REF TO if_cds_test_environment.
54
+
55
+ " IMPORTANT: class_setup/teardown must be CLASS-METHODS (static)!
56
+ CLASS-DATA mo_cds_env_static TYPE REF TO if_cds_test_environment.
57
+
58
+ METHODS setup.
59
+ METHODS test_cds_with_doubles FOR TESTING.
60
+
61
+ CLASS-METHODS: class_setup,
62
+ class_teardown.
63
+
64
+ ENDCLASS.
65
+
66
+ "-------------------------
67
+ " CLASS IMPLEMENTATION
68
+ "-------------------------
69
+ CLASS ltcl_cds_test IMPLEMENTATION.
70
+
71
+ METHOD class_setup.
72
+ " Create CDS test environment — framework auto-creates doubles for dependencies
73
+ mo_cds_env_static = cl_cds_test_environment=>create(
74
+ i_for_entity = 'ZC_MY_CDS_VIEW' ).
75
+ ENDMETHOD.
76
+
77
+ METHOD class_teardown.
78
+ " Clean up test environment
79
+ mo_cds_env_static->destroy( ).
80
+ ENDMETHOD.
81
+
82
+ METHOD setup.
83
+ " IMPORTANT: Assign static env to instance and clear doubles before each test
84
+ mo_cds_env = mo_cds_env_static.
85
+ mo_cds_env->clear_doubles( ).
86
+ ENDMETHOD.
87
+
88
+ METHOD test_cds_with_doubles.
89
+ " IMPORTANT: Must declare table type first — cannot inline in VALUE #()!
90
+ DATA lt_test_data TYPE TABLE OF zc_my_cds_view WITH EMPTY KEY.
91
+ lt_test_data = VALUE #(
92
+ ( field1 = 'A' field2 = 100 )
93
+ ( field1 = 'B' field2 = 200 ) ).
94
+
95
+ " Insert test data using named parameter
96
+ mo_cds_env->insert_test_data( i_data = lt_test_data ).
97
+
98
+ " Select from CDS view
99
+ SELECT * FROM zc_my_cds_view INTO TABLE @DATA(lt_result).
100
+
101
+ " Verify results
102
+ cl_abap_unit_assert=>assert_not_initial(
103
+ act = lt_result
104
+ msg = 'Result should not be empty' ).
105
+
106
+ cl_abap_unit_assert=>assert_equals(
107
+ act = lines( lt_result )
108
+ exp = 2
109
+ msg = 'Expected 2 rows' ).
110
+ ENDMETHOD.
111
+
112
+ ENDCLASS.
113
+ ```
114
+
115
+ ---
116
+
117
+ ## 3. Testing CDS Views with Aggregations (SUM, COUNT, GROUP BY)
118
+
119
+ For CDS views with aggregations, insert test data into the **base tables** (SFLIGHT, SCARR,
120
+ SBOOK, etc.), not directly into the CDS view. The framework routes the inserts through the
121
+ aggregation pipeline.
122
+
123
+ ```abap
124
+ METHOD test_aggregation.
125
+ " Insert data into base tables via CDS test doubles
126
+ DATA lt_scarr TYPE TABLE OF scarr WITH EMPTY KEY.
127
+ lt_scarr = VALUE #( ( carrid = 'LH' carrname = 'Lufthansa' currcode = 'EUR' ) ).
128
+ mo_cds_env->insert_test_data( i_data = lt_scarr ).
129
+
130
+ DATA lt_sflight TYPE TABLE OF sflight WITH EMPTY KEY.
131
+ lt_sflight = VALUE #( ( carrid = 'LH' connid = '0400' fldate = '20240115'
132
+ seatsmax = 200 seatsocc = 100 ) ).
133
+ mo_cds_env->insert_test_data( i_data = lt_sflight ).
134
+
135
+ DATA lt_sbook TYPE TABLE OF sbook WITH EMPTY KEY.
136
+ lt_sbook = VALUE #(
137
+ ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0001' forcuram = 1000 )
138
+ ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0002' forcuram = 2000 )
139
+ ( carrid = 'LH' connid = '0400' fldate = '20240115' bookid = '0003' forcuram = 3000 ) ).
140
+ mo_cds_env->insert_test_data( i_data = lt_sbook ).
141
+
142
+ " Select from CDS view — aggregations will use test double data
143
+ SELECT * FROM zc_flight_revenue INTO TABLE @DATA(lt_result).
144
+
145
+ cl_abap_unit_assert=>assert_equals(
146
+ exp = 3
147
+ act = lt_result[ 1 ]-numberofbookings
148
+ msg = 'Should have 3 bookings' ).
149
+
150
+ cl_abap_unit_assert=>assert_equals(
151
+ exp = '6000.00'
152
+ act = lt_result[ 1 ]-totalrevenue
153
+ msg = 'Total revenue should be 6000.00' ).
154
+ ENDMETHOD.
155
+ ```
156
+
157
+ ---
158
+
159
+ ## 4. Testing CDS Views that Select from Another CDS View
160
+
161
+ > **Note:** This pattern applies when your design **already has** a CDS view that selects from
162
+ > another CDS view. It does NOT mean you should split a single view into two — use a single
163
+ > CDS view with GROUP BY / JOIN when the business logic fits.
164
+
165
+ When your CDS view selects from **another CDS view** (not a base table), `create` raises
166
+ `CX_CDS_FAILURE`. Use `create_for_multiple_cds` instead and list all CDS entities in the
167
+ dependency chain.
168
+
169
+ ```abap
170
+ METHOD class_setup.
171
+ " ZC_TopView selects from ZC_IntermediateView (another CDS view entity)
172
+ " → must use create_for_multiple_cds and list all CDS entities
173
+ mo_cds_env_static = cl_cds_test_environment=>create_for_multiple_cds(
174
+ i_for_entities = VALUE #(
175
+ ( 'ZC_TOPVIEW' ) " the view under test
176
+ ( 'ZC_INTERMEDIATEVIEW' ) " the CDS view it selects from
177
+ ) ).
178
+ ENDMETHOD.
179
+ ```
180
+
181
+ Insert test data into the **intermediate CDS view** (not the base tables), because that is
182
+ what the top-level view reads:
183
+
184
+ ```abap
185
+ METHOD test_read.
186
+ DATA lt_source TYPE TABLE OF zc_intermediateview WITH EMPTY KEY.
187
+ lt_source = VALUE #(
188
+ ( field1 = 'A' field2 = 100 )
189
+ ( field1 = 'B' field2 = 200 ) ).
190
+ mo_cds_env->insert_test_data( i_data = lt_source ).
191
+
192
+ SELECT * FROM zc_topview INTO TABLE @DATA(lt_result).
193
+
194
+ cl_abap_unit_assert=>assert_equals(
195
+ exp = 2 act = lines( lt_result ) msg = 'Expected 2 rows' ).
196
+ ENDMETHOD.
197
+ ```
198
+
199
+ **Rules:**
200
+ - List the view under test **and all CDS views it depends on** in `i_for_entities`
201
+ - Insert data into the **direct source** of the top-level view (the intermediate CDS view)
202
+ - Order in `i_for_entities` does not matter
203
+ - If `create` raises `CX_CDS_FAILURE`, switch to `create_for_multiple_cds`
204
+
205
+ ---
206
+
207
+ ## 5. Key Classes and Methods
208
+
209
+ | Item | Type / Usage |
210
+ |------|-------------|
211
+ | `CL_CDS_TEST_ENVIRONMENT` | Class — entry point, use its `CREATE` / `CREATE_FOR_MULTIPLE_CDS` methods |
212
+ | `IF_CDS_TEST_ENVIRONMENT` | Interface — declare your variable with this type |
213
+ | `CLASS-METHODS class_setup` | Must be static (`CLASS-METHODS`, not `METHODS`) |
214
+ | `CL_ABAP_UNIT_ASSERT` | Standard AUnit assertion class |
215
+
216
+ | Method | Purpose |
217
+ |--------|---------|
218
+ | `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Environment for a CDS view over base tables |
219
+ | `CL_CDS_TEST_ENVIRONMENT=>create_for_multiple_cds( i_for_entities = ... )` | Environment when CDS view selects from another CDS view |
220
+ | `insert_test_data( i_data = ... )` | Inject test rows into a test double |
221
+ | `clear_doubles( )` | Remove all test rows — call in `setup` before each test |
222
+ | `destroy( )` | Tear down the environment — call in `class_teardown` |
223
+
224
+ ---
225
+
226
+ ## 6. Important Usage Notes
227
+
228
+ 1. **Declare with interface type**: `DATA mo_cds_env TYPE REF TO if_cds_test_environment` —
229
+ `create` returns an interface reference, not a class reference.
230
+
231
+ 2. **Static lifecycle methods**: `class_setup` and `class_teardown` must be `CLASS-METHODS`
232
+ (not `METHODS`). The environment is expensive to create — build it once per class run.
233
+
234
+ 3. **Table type before VALUE #()**: Must declare `DATA lt_tab TYPE TABLE OF <type> WITH EMPTY KEY`
235
+ before using `VALUE #()` — inline declaration inside `VALUE #()` is not supported here.
236
+
237
+ 4. **Auto-created dependencies**: When the CDS view selects only from base tables, the framework
238
+ auto-creates test doubles — do not specify an `i_dependency_list`. When the CDS view selects
239
+ from another CDS view, use `create_for_multiple_cds` (see section 4).
240
+
241
+ 5. **Aggregations**: For CDS views with SUM/COUNT/GROUP BY, insert test data into the base tables
242
+ (SFLIGHT, SCARR, etc.), not the CDS view itself.
243
+
244
+ 6. **Clear doubles**: Always call `clear_doubles` in `setup` to ensure test isolation.
245
+
246
+ 7. **Enable associations**: Set `test_associations = 'X'` in `create` only when explicitly
247
+ testing CDS association navigation.
24
248
 
25
- See `abapgit-agent ref --topic testing` for full code examples including:
26
- - Basic CDS test double setup
27
- - Testing CDS views with aggregations (insert into base tables)
28
- - Testing CDS views that select from another CDS view (`create_for_multiple_cds`)
249
+ 8. **Exception handling**: Declare test methods with `RAISING cx_static_check` if the code
250
+ under test raises checked exceptions.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: CDS Views
4
- nav_order: 5
4
+ nav_order: 9
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: Classes & Objects
4
- nav_order: 6
4
+ nav_order: 4
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
@@ -0,0 +1,249 @@
1
+ ---
2
+ layout: default
3
+ title: Documentation Comments
4
+ nav_order: 6
5
+ parent: ABAP Coding Guidelines
6
+ grand_parent: ABAP Development
7
+ ---
8
+
9
+ # ABAP Documentation Comments
10
+
11
+ **Searchable keywords**: ABAP DOC, "! comment, shorttext synchronized, @parameter, @raising, inline comment, CDS comment, // comment, program header, *&---, documentation comment
12
+
13
+ ## TOPICS IN THIS FILE
14
+ 1. Two Types of Comments - line 18
15
+ 2. OO Class Documentation (CLAS) - line 37
16
+ 3. Interface Documentation (INTF) - line 101
17
+ 4. Program Header (PROG) - line 120
18
+ 5. CDS View Comments (DDLS) - line 137
19
+ 6. When NOT to Comment - line 161
20
+ 7. Quick Decision Table - line 182
21
+
22
+ ---
23
+
24
+ ## 1. Two Types of Comments
25
+
26
+ ABAP has two distinct comment styles with different purposes:
27
+
28
+ **`"!` (ABAP DOC)** — parsed by the ABAP system; surfaced in ADT and SE24 as F2 help.
29
+ Use for API-level documentation: class declarations, interface declarations, and method signatures.
30
+ This is the equivalent of Javadoc. The system reads it — it is metadata, not decoration.
31
+
32
+ **`"!` is only valid immediately before these statements:**
33
+ `CLASS ... DEFINITION`, `INTERFACE`, `METHODS`, `CLASS-METHODS`, `EVENTS`, `DATA`, `CLASS-DATA`, `CONSTANTS`.
34
+
35
+ **`"!` before `TYPES` is a syntax error** — the Code Inspector reports "ABAP Doc comment is in the wrong position."
36
+ Use a regular `"` comment to describe type structures instead.
37
+
38
+ **`"` (regular inline comment)** — source-only; not parsed by the ABAP system.
39
+ Use inside method bodies to explain non-obvious logic, and to label `TYPES` blocks.
40
+ Never use `"!` inside method implementations — it has no effect there.
41
+
42
+ **Default behaviour (when to add automatically vs. only on request):**
43
+
44
+ | Comment Type | Default Behaviour |
45
+ |---|---|
46
+ | `"! <p class="shorttext synchronized">` on CLASS/INTF | **Always auto-add** — synced to XML `<DESCRIPT>`; it IS object metadata |
47
+ | `@EndUserText.label` on CDS view | **Always auto-add** — same: it IS the CDS description |
48
+ | `"!` + `@parameter` on INTF public methods | **Always auto-add** — interfaces are the contract; self-documenting |
49
+ | `"!` + `@parameter` on CLAS public methods | **Auto-add** when creating a new class from scratch |
50
+ | `"!` on existing CLAS private/protected methods | **Only if requested** — adding to existing code is refactoring |
51
+ | `"` inline comments inside method bodies | **Only when non-obvious** — never add redundant comments |
52
+ | `*&---` program header | **Always auto-add** — standard for every PROG |
53
+
54
+ ---
55
+
56
+ ## 2. OO Class Documentation (CLAS)
57
+
58
+ ### Class-level shorttext
59
+
60
+ Place the `"!` shorttext immediately before `CLASS ... DEFINITION`:
61
+
62
+ ```abap
63
+ "! <p class="shorttext synchronized">Pull ABAP objects from a remote git repository</p>
64
+ CLASS zcl_abgagt_agent DEFINITION PUBLIC FINAL CREATE PUBLIC.
65
+ ```
66
+
67
+ This shorttext is **synced to the XML `<DESCRIPT>` field** by abapGit. Creating a class without
68
+ it means the XML description is blank and the object cannot be searched by description in SE24/SE80.
69
+ **Always add it** when creating any new class.
70
+
71
+ **Note on `*"*` auto-header:** When a class has local definitions or inherits from another class,
72
+ abapGit writes a 3-line `*"*"` block at the top of the `.clas.abap` file:
73
+
74
+ ```abap
75
+ *"* use this source file for the definition and implementation of
76
+ *"* local helper classes, interface definitions and type
77
+ *"* temporary on-the-fly implementation
78
+ ```
79
+
80
+ In that case, the `"!` shorttext goes on line 4 (after the block), not line 1.
81
+
82
+ ### Method documentation
83
+
84
+ Place `"!` documentation in the DEFINITION section, PUBLIC SECTION only, immediately before the
85
+ `METHODS` statement:
86
+
87
+ ```abap
88
+ "! Pull files from remote and activate them
89
+ "! @parameter it_files | List of files to activate (relative paths)
90
+ "! @parameter rv_success | True if all objects activated successfully
91
+ "! @raising zcx_abapgit_exception | If pull or activation fails
92
+ METHODS pull_files
93
+ IMPORTING it_files TYPE string_table
94
+ RETURNING VALUE(rv_success) TYPE abap_bool
95
+ RAISING zcx_abapgit_exception.
96
+ ```
97
+
98
+ **Rules:**
99
+
100
+ - **ALWAYS add** `"! <p class="shorttext synchronized">` when creating any new CLASS — no exceptions.
101
+ - **ALWAYS add** `"!` + `@parameter` for all PUBLIC methods when creating a new class from scratch.
102
+ - When **modifying existing** code, only add or update comments if explicitly asked.
103
+ - `@parameter <name> | <description>` — one line per IMPORTING/EXPORTING/RETURNING/CHANGING param.
104
+ - `@raising <exception> | <reason>` — one line per RAISING exception.
105
+ - PRIVATE and PROTECTED methods: optional; add only if the purpose is non-obvious.
106
+ - Place ONLY in the DEFINITION section — do NOT repeat `"!` in the IMPLEMENTATION section.
107
+
108
+ **Full example:**
109
+
110
+ ```abap
111
+ "! <p class="shorttext synchronized">Syntax checker for ABAP class source</p>
112
+ CLASS zcl_abgagt_syntax_chk_clas DEFINITION PUBLIC FINAL CREATE PUBLIC.
113
+ PUBLIC SECTION.
114
+ INTERFACES zif_abgagt_syntax_checker.
115
+
116
+ "! Create a new syntax checker instance
117
+ "! @parameter ii_agent | Agent used for HTTP communication
118
+ CLASS-METHODS create
119
+ IMPORTING ii_agent TYPE REF TO zif_abgagt_agent
120
+ RETURNING VALUE(ro_check) TYPE REF TO zif_abgagt_syntax_checker.
121
+
122
+ PRIVATE SECTION.
123
+ DATA mi_agent TYPE REF TO zif_abgagt_agent.
124
+ ENDCLASS.
125
+ ```
126
+
127
+ ---
128
+
129
+ ## 3. Interface Documentation (INTF)
130
+
131
+ Interfaces follow the same `"!` pattern as classes. The shorttext goes immediately before
132
+ `INTERFACE ... PUBLIC`, and every method gets `"!` + `@parameter`.
133
+
134
+ ```abap
135
+ "! <p class="shorttext synchronized">Contract for all syntax checker implementations</p>
136
+ INTERFACE zif_abgagt_syntax_checker PUBLIC.
137
+
138
+ "! Check the syntax of ABAP source code
139
+ "! @parameter iv_source | Full ABAP source text to check
140
+ "! @parameter rv_result | JSON-encoded result with errors list
141
+ "! @raising zcx_abapgit_exception | On communication failure
142
+ METHODS check_syntax
143
+ IMPORTING iv_source TYPE string
144
+ RETURNING VALUE(rv_result) TYPE string
145
+ RAISING zcx_abapgit_exception.
146
+
147
+ ENDINTERFACE.
148
+ ```
149
+
150
+ **Canonical example:** `zif_abgagt_syntax_checker.intf.abap` in this repository.
151
+
152
+ **Rules:**
153
+ - **ALWAYS add** `"! <p class="shorttext synchronized">` for every new interface.
154
+ - **ALWAYS add** `"!` + `@parameter` for every method — interfaces are the published contract.
155
+ - No exceptions for "obvious" method names — document them anyway.
156
+
157
+ ---
158
+
159
+ ## 4. Program Header (PROG)
160
+
161
+ Programs use the traditional `*&---` block, NOT ABAP DOC. Place it before the `REPORT` statement:
162
+
163
+ ```abap
164
+ *&---------------------------------------------------------------------*
165
+ *& Report Z_MY_PROGRAM
166
+ *&---------------------------------------------------------------------*
167
+ *& Brief description of what the program does
168
+ *&---------------------------------------------------------------------*
169
+ REPORT z_my_program.
170
+ ```
171
+
172
+ **Rules:**
173
+ - **ALWAYS add** this header block when creating any new program.
174
+ - Do NOT add `"! <p class="shorttext synchronized">` before `REPORT` — it is not parsed there.
175
+ - Inline comments inside `START-OF-SELECTION` and other events use the regular `"` style.
176
+
177
+ ---
178
+
179
+ ## 5. CDS View Comments (DDLS)
180
+
181
+ CDS DDL source (`.ddls.asddls`) uses a completely different comment syntax from ABAP:
182
+
183
+ - Line comment: `// text`
184
+ - Block comment: `/* text */`
185
+
186
+ **Never use ABAP-style `"` inside CDS source** — it causes a CDS syntax error.
187
+
188
+ ### `@EndUserText.label` — the CDS equivalent of shorttext
189
+
190
+ This annotation IS the object description. Always include it before the view entity definition:
191
+
192
+ ```cds
193
+ @EndUserText.label: 'Revenue summary by carrier'
194
+ define view entity ZC_FlightRevenue
195
+ as select from sflight
196
+ {
197
+ key carrid, // IATA carrier code
198
+ key connid, // Connection number
199
+ sum( price ) as TotalRevenue
200
+ }
201
+ ```
202
+
203
+ **Rules:**
204
+ - **ALWAYS add** `@EndUserText.label` when creating any new CDS view entity.
205
+ - Add `// text` line comments after non-obvious field names.
206
+ - Use `/* ... */` for multi-line block comments if needed (e.g., explaining a complex join).
207
+ - No `"!` or `"` comments anywhere in `.ddls.asddls` files.
208
+
209
+ ---
210
+
211
+ ## 6. When NOT to Comment
212
+
213
+ The guiding principle: **comments explain *why*, not *what***.
214
+
215
+ ```abap
216
+ " BAD — repeats the code, adds no value
217
+ ls_params-mode = 'abort'. " Set mode to abort
218
+
219
+ " GOOD — explains a non-obvious rule
220
+ ls_params-mode = 'abort'. " INITIAL means abort (caller omitting the field = abort semantics)
221
+ ```
222
+
223
+ **Do NOT add comments when:**
224
+ - The comment would just restate the variable name or method call.
225
+ - A private helper method simply delegates to an interface method (the name is self-explanatory).
226
+ - `@parameter` description would be identical to the parameter name (e.g., `"! @parameter iv_name | Name`).
227
+ - You are modifying existing code and the task did not ask for documentation changes.
228
+
229
+ **DO add comments when:**
230
+ - The logic involves a non-obvious ABAP-specific behaviour or workaround.
231
+ - There is a caller precondition that cannot be expressed in the method signature.
232
+ - A COND/SWITCH mapping table needs to explain the business rule behind each branch.
233
+ - A loop exit or CONTINUE has a non-obvious condition.
234
+
235
+ ---
236
+
237
+ ## 7. Quick Decision Table
238
+
239
+ | Object | Where | Style | Required? |
240
+ |--------|-------|-------|-----------|
241
+ | CLAS (global) | Before `CLASS DEFINITION` | `"! <p class="shorttext synchronized">` | **Always** |
242
+ | CLAS public method | Before `METHODS` in DEFINITION | `"! desc` + `"! @parameter` | Yes (new objects) |
243
+ | CLAS private/protected method | Before `METHODS` in DEFINITION | `"! desc` | Only if non-obvious |
244
+ | INTF method | Before `METHODS` in interface | `"! desc` + `"! @parameter` | **Always** |
245
+ | PROG | First lines before `REPORT` | `*&---` block | **Always** |
246
+ | DDLS view entity | Before `define view entity` | `@EndUserText.label` annotation | **Always** |
247
+ | DDLS field | After field name | `// text` | For non-obvious fields |
248
+ | Method body | Inside `METHOD...ENDMETHOD` | `" text` | Only for non-obvious logic |
249
+ | TYPES block | Before `TYPES:` in interface/class | `" text` | Optional — `"!` is invalid here |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: Common ABAP Errors
4
- nav_order: 14
4
+ nav_order: 12
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: Dump Analysis Guide
4
- nav_order: 16
4
+ nav_order: 19
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: Debug Session Guide
4
- nav_order: 15
4
+ nav_order: 18
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---
@@ -20,6 +20,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
20
20
  | `cds.md` | CDS Views |
21
21
  | `classes.md` | ABAP Classes and Objects |
22
22
  | `objects.md` | Object Naming Conventions |
23
+ | `naming-limits.md` | Naming Length Limits (30/16/40 char rules per type) |
23
24
  | `json.md` | JSON Handling |
24
25
  | `abapgit.md` | abapGit XML Metadata Templates |
25
26
  | `unit-testable-code.md` | Unit Testable Code Guidelines (Dependency Injection) |
@@ -31,6 +32,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
31
32
  | `object-creation.md` | Object Creation (XML metadata, local classes) |
32
33
  | `cds-testing.md` | CDS Testing (Test Double Framework) |
33
34
  | `abaplint.md` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
35
+ | `comments.md` | Documentation Comments (ABAP DOC, shorttext, @parameter, CDS //) |
34
36
 
35
37
  ## Usage
36
38
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  layout: default
3
3
  title: JSON Handling
4
- nav_order: 8
4
+ nav_order: 11
5
5
  parent: ABAP Coding Guidelines
6
6
  grand_parent: ABAP Development
7
7
  ---