Introduction
In Custom ABAP Development Methodology whitepaper – Custom ABAP Development Methodology – I presented a custom development methodology that takes into consideration possibility of multiple development components implementing a functionality described in a single technical specification document. If we acknowledge that fact and design our development process to take advantage of it, we could build up libraries of reusable components that could be utilized in different custom programs described in multiple functional/technical specification documents or even being part of multiple projects. The component reusability across multiple technical specification documents is shown on the following screen:
In order to reuse custom development components in multiple custom programs, you have to have ability to document well their functionality and make documentation easily available to the entire development team. The word processor based technical specification documents are usually not at developer fingertips for easy access and quick reference. ABAP Docs 2.0 – the inline documentation system described in Upgrade to ABAP Docs 2.0 and Contribute to Its Development in Google™ Code Community Project whitepaper, with links to its source code and user manuals, fulfills that gap. Its use is incorporated in the following development process diagram:
Once splitting of technical specification into development components is sign off, the development process of ABAP components shown in red-dotted squares starts. The following sections of this document will describe in detail the development process for a sample custom ABAP Form.
Component Description
To illustrate the development cycle that utilizes ABAP Docs, let us develop a sample ABAP Form that would retrieve the address information of sold-to, ship-to, payer, bill-to or any other type of business partner that is referenced in order document. We would use ABAP Docs 2.0 to accomplish it. Let us assume, that ABAP Form will be named ZSDC_DOC_BP_ADDR_GET and it will be stored in ZSDC_DOC_I ABAP include belonging to ZSDC package.
The other component types could be also used to show the development cycle; e.g., ZFUNC, ZMETH. However, ZFORM was chosen to show all steps of the development cycle; e.g., for ZFUNC component there is no need to write a test program – the test capability of SE37 transaction can be use to accomplish it.
The following sections describe development process steps for sample ABAP Form as well as they indicate team members login names that are responsible for implementing them; e.g.,
Step 2 – ARCHITECT – Defining ABAP Form Signature.
To make role division easy to understand, the ARCHITECT, the DEVELOPER1 and the DEVELOPER2 login names are used.
Step 1 – ARCHITECT - Inserting ABAP Form Pattern
On the ABAP Docs main screen, select any component of the same type as one you want to create; i.e., FORM, as shown on the following screen:
The SE38 transaction screen appears. Enter the name of include where you want to place a new ABAP Form, e.g., ZSDC_DOC_I and click on CHANGE or CREATE button depending on situation. Once, ABAP Editor window appears, place the cursor at position where you want to enter a new ABAP Form and click on PATTERN button. The ABAP patterns popup window appears as shown on the following screen:
Select Other Pattern radio button and enter ZFORM in a field below it. Then, click on OK button. The ABAP Docs pattern for ABAP Form inline documentation is inserted at cursor position as shown on the following screen:
Converting ABAP Form Pattern into Inline Documentation
The ABAP Form pattern – ZFORM – as well as patterns for other component types consist of multiple sections; e.g., DESCRIPTION, TECHNICAL, FORM, USING, EXPORTING, METHOD and many others. The section header line starts in column 1 with letter or STAR character and the second character is always different than SPACE. The section content follows the section header and always has a SPACE character in column 2 and very often STAR in column 1. The section content ends with the next section header line.
Some sections are just comment lines; e.g., DSESCRIPTION section, and some are live ABAP code lines; e.g., CHANGING section. Most sections are optional and their header lines and content can be removed; e.g., SEE_ALSO and TABLES sections can be removed if not needed.
To convert pattern to inline documentation, modify pattern content changing it to reflect definition/description of component being documented. In the process, make sure that the structure of template is not changed.
For more details, please, refer to ABAP Docs 2.0 User Manual referenced in Upgrade to ABAP Docs 2.0 and Contribute to Its Development in Google™ Code Community Project whitepaper.
Step 2 – ARCHITECT - Defining ABAP Form Signature
Once ABAP Form pattern is inserted into ZSDC_DOC_I ABAP include, modify its FORM and USING sections to represent signature of ZSDC_DOC_BP_ADDR_GET ABAP Form and remove not needed TABLES and CHANGING sections as shown on the following screen:
Note, that one and only one line is occupied by ABAP Form name and each of it’s parameters.
Step 3 – ARCHITECT - Defining ABAP Form Descriptive Sections
Now it is time to provide more descriptive information about ABAP Form being developed.
The TECHNICAL section will provide implementation details for the developer of the component. The DESCRIPTION and EXAMPLES sections will be very useful for the developers that would utilize the component in the current program being developed and many new programs to be developed in the future.
The descriptive sections might look as shown on the following screen:
Figure 7 – ABAP Docs Documentation Descriptive Sections for ZSDC_DOC_BP_ADDR_GET ABAP Form
Notice, that sections use limited HTML formatting; e.g.,
,You can experiment with other HTML tags to make you help document looking better.
Step 4 – ARCHITECT – Eliminate SEE_ALSO Section
The SEE_ALSO section can be eliminated from the pattern due to auto reference feature implemented in ABAP Docs 2.0.
Step 5 – ARCHITECT – Initial Setting of STATUS Section
The STATUS section allows defining statuses for 3 stages of the implementation process; i.e., SPECIFICATION, DEVELOPMENT and TESTING. The following statuses can be used for each of those stages: PENDING, STARTED, SUSPENDED, RESUMED and COMPLETED. Those statuses are shown in the section’s header line. The STATUS section consists of 3 lines for 3 stages of the development process. After the development stage name; e.g., TESTING, enter developer’s login name, current status and the date in YYYYMMDD format as shown on the following screen:
Figure 8 – ABAP Docs Documentation STATUS Section
The login names, statuses texts, their corresponding icon representations and dates are displayed in the ABAP Docs component list. They can be also used on the selection screen to search for specific components; e.g, to-do-list of components that were assigned for DEVELOPMENT to DEVELOPER1 and are in PENDING status:
Figure 9 – Selecting PENDING Components for DEVELOPMENT for DEVELOPER1
Click on EXECUTE button and the following list may appear:
Figure 10 – List of PENDING Components for DEVELOPMENT for DEVELOPER1
This way DEVELOPER1 may find easily what components were assigned to him/her for development. Once he/she would finish development he/she could change the DEVELOPMENT status to COMPLETED, activate ABAP include and regenerate HTML help. Than the DEVELOPER2 responsible for testing might select his/her to-do-list; i.e., all components assigned for TESTING to DEVELOPER2 in PENDING testing status and COMPLETED development status as shown on the following screen:
Figure 11 – Selecting PENDING Components for TESTING for DEVELOPER2
Step 6 – ARCHITECT – Implement ABAP Form Simulation
Some ABAP Forms might be very complex and it might take several days or even longer to implement them. To speed up the development process of the application that would use that component, you might implement component’s simulation before handing component for development to; e.g., DEVELOPER1.
Implementing component simulation would allow testing the logic of the application before component is developed. When the application would call the component, its hard coded simulation routine will be executed instead. This might be good enough for preliminary application’s testing.
To implement component simulation you have to:
A – Make sure that a global parameter ALLOW_SIMULATION is set to YES in ZFLC21 transaction for ZABAP_DOCS application as shown on the following screen:
Figure 12 – ALLOW_SIMULATION Flag set to YES in ZFLC21
B - On ABAP Docs component list, click on component’s 
active icon. It will be changed to 
simulation icon. This would change component to simulation mode for this specific user. The other users; e.g., DEVLOPER1 will be still executing component in the active mode that would allow testing ABAP code being developed. The ABAP Docs list with simulated component will look as shown on the following screen:
Figure 13 – Component changed to Simulation Mode for this user
C – Develop simulation routine in the same ABAP include; e.g., ZSDC_DOC_I, and call it from ABAP Form being developed as shown on the following screen:
Figure 14 – Simulation Routine
D – The ABAP include; e.g., ZSDC_DOC_I, containing ABAP Form being developed and its simulation routine should be part of ABAP Subroutine Pool; e.g, ZSDC_DOC_SP shown on the following screen:
Figure 15 – Subroutine Pool
E – Call not yet developed ABAP Form from the application program that you want to test before component is developed, as shown on the following screen:
Figure 16 – Sample Application
Step 7 – ARCHITECT – Activate Component and Generate Its HTML Help
Now you are ready to publish component documentation for the developer. Activate ABAP include containing ABAP Form prototype; i.e., signature plus simulation call. Then, return to ABAP Docs. Click on Generate Modified/List button. Enter ABAP include name; e.g., ZSDC_DOC_I, and click on EXECUTE button. Return back to ABAP Docs and click on REFRESH button to get the new component included in the ABAP Docs list.
Step 8 – DEVELOPER1 – Monitoring List of Component for Development
The developer enters selection criteria to get his/her to-do-list; i.e., the list of components assigned to him/her for development with PENDING status as shown on the following screen:
Figure 17 – Selecting PENDING Components for DEVELOPMENT for DEVELOPER1
Click on EXECUTE button and the developer’s to-do-list will appear as shown on the following screen:
Figure 18 – List of PENDING Components for DEVELOPMENT for DEVELOPER1
This way DEVELOPER1 may find easily what components were assigned to him/her for development and display their description as shown on the following screen:
Figure 19 – Component ABAP Docs HTML Documentation
This could be the starting point for the developer to implement the component and test its real logic rather than simulation logic that others can use before component is completed.
Step 9 – DEVELOPER1 – Developing Component Business Logic
The developer selects component and clicks on CHANGE button. The SE38 ABAP Edior is displayed with the name of ABAP include containing ABAP component prototype. Click on CHANGE button and develop component business logic as shown on the following screen:
Figure 20 – Component ABAP Code
Note the usage of ZFLC_ON_ERROR_EXIT library macro – distributed and documented with ABAP Docs – for error handling. It allows handling errors in one line of ABAP code making business logic more readable and not obstructed by usually bulky error handling code.
Step 10 – DEVELOPER1 – Testing Component
Every component before being used in application programs should be tested. Testing ABAP Forms requires writing a small ABAP program that is integrated with ABAP Docs system. Select newly developed ZSDC_DOC_BP_ADDR_GET ABAP Form on the ABAP Docs list and click on the TEST button. The SE38 ABAP Editor appears with the name of the test program to be developed; i.e., YSDC_DOC_BP_ADDR_GET. Note that the name of the program is the same as the name of ABAP Form except the first letter Z changed to Y.
Create the test program as shown on the following screen:
Run the program with different test cases to test fully component. Save test cases as variants to allow others to repeat testing.
Step 11 – DEVELOPER1 – Change Component Status
If you are happy with testing results, change component DEVELOPMENT status to COMPLETED as shown on the following screen:
You can also adjust documentation if necessary. Than, activate code, return to ABAP Docs and regenerate ABAP Docs documentation. If you would search again for components assigned to DEVELOPER1 for DEVELOPMENT that are in PENDING status, you will not find that component anymore on the list.
Step 12 – DEVELOPER2 – Test Component in Application
Once component was unit tested by DEVELOPER1 using the test program, it is time for someone else to test it in the application program. The DEVELOPER2 will see the component on his/her to-do-list selecting components ready for testing; i.e., with COMPLETED DEVELOPMENT status and assigned to DEVELOPER2 with PENDING TESTING status as shown on the following screen:
Figure 23 – Selecting PENDING Components for TESTING for DEVELOPER2
Click on EXECUTE button and you will see the component on the list as shown on the following screen:
Figure 24 – List of Component with COMPLETED development and PENDING testing for DEVELOPER2
Once application level testing is completed, change TESTING status to COMPLETED as shown on the following screen:
Then, activate ABAP Code and regenerate ABAP Docs Help. The development cycle for ABAP Form is completed.
Summary
As you can see, ABAP Docs is more than just a simple help system. Beside its basic functions of maintaining, searching and presenting components’ documentation, it allows additionally to:
- Simulate components that are not yet fully developed, as long as components’ prototype; i.e., signature and simulation routines, are defined
- Maintain components development cycle status and display to-do-list for developers to work on specification, development or testing of the component
I hope that this whitepaper would make it easier to take full advantage of ABAP Docs features in your daily work.
This whitepaper and full source code of sample ABAP Form, its test programs and a sample application are available for download on http://code.google.com/p/abap-docs/ Web page. Select there Show All downloads link and then download ADOC_WP_03 - Implementing ABAP Form with ABAP Docs.zip file with MS Word® version of this whitepaper and source code used in examples.
1 Comment
