In this idea snippet I would like to share some thoughts on how to use implicit enhancement options for documenting, or why it's not a good idea at all.
First some background: company I work for produces ABAP software in its own naming space. These modules are then delivered to the customer systems. Among others we have also a common module with logic which is reused by all other modules. In this module there is also a method for determining the customer ID for current user. It is the same throughout the systems. But by one customer, there is an alternation: whereas our standard logic reuses the standard way to determine the customer ID, the Z-logic, which could be also an enhancement to our standard, uses some other way, with one additional input parameter. Since I didn't know it, I used our standard way in the Z-logic, and before anybody realised that my new code was not working properly, it was sent to the production system (as shared part with some other project, which was already accepted). The results are easy to imagine.
So I was doing some thinking: what could be done better, to avoid such mistakes in the future? Of course, one could say: document the customer specifics and store the documentation in a place that's available for all developers. But on the other hand: many people just start developing without looking into the documentation which is stored somewhere in the companys local network. So the documentation has to be as close to the code as possible.
As for me, when I'm developing, I always use the code completion. This tool gives me as a hint for a method its complete signature, including the description. So let's define a new parameter in the standard method. If this new parameter is supplied, the Z-method will be called and the standard logic will be skipped; otherwise only the standard would be executed. In the description for this parameter I can point to the long text of the enhancement implementation, where customer specifics are documented. Now there is no way to overlook the documentation! Great idea, isn't it?
Now it comes to the usage of this brand new documenting technique. My code completion hint informs me that there is a new parameter, but skips its description?!
Perhaps if I'd have used the pattern functionality?
No, not any better. Drag'n'drop?
Still not any better.
But actually it's even worse! In the above case I'm enhancing a Z-class from my $TMP package and calling the enhanced method from within the class. In my real world scenario, I want to call the enhanced method from outside the class. In this case code completion skips not only the description, by the new parameter too!
The other two variants (Pattern function and drag'n'drop) work in this case the same.
Wait a minute! We do have the new ABAP Development Tools (aka ABAP in Eclipse). It is definitely better in that tool!
Poor me, still not any better.
I find the idea quite good (perhaps only because it's mine?), but it's pretty useless, the way the code completion works. And of course there are still some developers that type all the method names and parameters manually. I tested this approach in a 7.51 system, but perhaps more relevant is the kernel version.
I hope this short blog could be useful for someone, even if this documenting technique does not (yet?) fulfill the expectations. And how do you maintain your documentation so that such crucial informations can be found easily?
Best regards
Michał Badura
First some background: company I work for produces ABAP software in its own naming space. These modules are then delivered to the customer systems. Among others we have also a common module with logic which is reused by all other modules. In this module there is also a method for determining the customer ID for current user. It is the same throughout the systems. But by one customer, there is an alternation: whereas our standard logic reuses the standard way to determine the customer ID, the Z-logic, which could be also an enhancement to our standard, uses some other way, with one additional input parameter. Since I didn't know it, I used our standard way in the Z-logic, and before anybody realised that my new code was not working properly, it was sent to the production system (as shared part with some other project, which was already accepted). The results are easy to imagine.
So I was doing some thinking: what could be done better, to avoid such mistakes in the future? Of course, one could say: document the customer specifics and store the documentation in a place that's available for all developers. But on the other hand: many people just start developing without looking into the documentation which is stored somewhere in the companys local network. So the documentation has to be as close to the code as possible.
As for me, when I'm developing, I always use the code completion. This tool gives me as a hint for a method its complete signature, including the description. So let's define a new parameter in the standard method. If this new parameter is supplied, the Z-method will be called and the standard logic will be skipped; otherwise only the standard would be executed. In the description for this parameter I can point to the long text of the enhancement implementation, where customer specifics are documented. Now there is no way to overlook the documentation! Great idea, isn't it?
Now it comes to the usage of this brand new documenting technique. My code completion hint informs me that there is a new parameter, but skips its description?!
Perhaps if I'd have used the pattern functionality?
No, not any better. Drag'n'drop?
Still not any better.
But actually it's even worse! In the above case I'm enhancing a Z-class from my $TMP package and calling the enhanced method from within the class. In my real world scenario, I want to call the enhanced method from outside the class. In this case code completion skips not only the description, by the new parameter too!
The other two variants (Pattern function and drag'n'drop) work in this case the same.
Wait a minute! We do have the new ABAP Development Tools (aka ABAP in Eclipse). It is definitely better in that tool!
Poor me, still not any better.
I find the idea quite good (perhaps only because it's mine?), but it's pretty useless, the way the code completion works. And of course there are still some developers that type all the method names and parameters manually. I tested this approach in a 7.51 system, but perhaps more relevant is the kernel version.
I hope this short blog could be useful for someone, even if this documenting technique does not (yet?) fulfill the expectations. And how do you maintain your documentation so that such crucial informations can be found easily?
Best regards
Michał Badura
- SAP Managed Tags:
4 Comments
| User | Count |
|---|---|
| 6 | |
| 5 | |
| 3 | |
| 3 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 1 | |
| 1 |
