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.
- package/abap/.github/copilot-instructions.slim.md +35 -4
- package/abap/CLAUDE.md +70 -53
- package/abap/guidelines/abapgit-fugr.md +20 -4
- package/abap/guidelines/abapgit-xml-only.md +69 -13
- package/abap/guidelines/abapgit.md +3 -2
- package/abap/guidelines/abaplint-local.md +1 -1
- package/abap/guidelines/abaplint.md +1 -1
- package/abap/guidelines/branch-workflow.md +1 -1
- package/abap/guidelines/cds-testing.md +233 -11
- package/abap/guidelines/cds.md +1 -1
- package/abap/guidelines/classes.md +1 -1
- package/abap/guidelines/comments.md +249 -0
- package/abap/guidelines/common-errors.md +1 -1
- package/abap/guidelines/debug-dump.md +1 -1
- package/abap/guidelines/debug-session.md +1 -1
- package/abap/guidelines/index.md +2 -0
- package/abap/guidelines/json.md +1 -1
- package/abap/guidelines/naming-limits.md +160 -0
- package/abap/guidelines/object-creation.md +18 -15
- package/abap/guidelines/objects.md +6 -3
- package/abap/guidelines/testing.md +4 -202
- package/abap/guidelines/unit-testable-code.md +1 -1
- package/abap/guidelines/workflow-detailed.md +1 -1
- package/package.json +1 -1
- package/abap/.github/copilot-instructions.md +0 -264
|
@@ -1,28 +1,250 @@
|
|
|
1
1
|
---
|
|
2
2
|
layout: default
|
|
3
3
|
title: CDS Testing
|
|
4
|
-
nav_order:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
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
|
-
|
|
26
|
-
|
|
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.
|
package/abap/guidelines/cds.md
CHANGED
|
@@ -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 |
|
package/abap/guidelines/index.md
CHANGED
|
@@ -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
|
|