Development Standards Guidelines 335678 (1)

J:\Webdocs\cms AMS Website\Training-Documentation\Guides and Standards\Development standards & guidelines .doc

Programming Standards and Guidelines

ADMINISTRATIVE MANAGEMENT SYSTEMS

May 10, 2005

AMS _____________________________________________________________________________________

__________________________________________________________________________ 2

Table of contents

Purpose....................................................................................................................................................... 3 Objective..................................................................................................................................................... 3 Scope .......................................................................................................................................................... 3 Technical review......................................................................................................................................... 4 Pre-coding phase........................................................................................................................................ 4 Coding ........................................................................................................................................................ 6

ABAP Workbench ................................................................................................................................ 7 ABAP4 Query ..................................................................................................................................... 15 Report Writer/Painter......................................................................................................................... 15 Drilldown reporting............................................................................................................................. 15 Cognos ................................................................................................................................................ 15 Web development .............................................................................................................................. 16

Technical Walkthrough ............................................................................................................................ 17 Level 1 Testing.......................................................................................................................................... 17 Open issues............................................................................................................................................... 18 Appendix A References to documents .................................................................................................. 19 Appendix B List of “common” function modules................................................................................. 20 Appendix C Technical Specifications Details....................................................................................... 21 Appendix D Walkthrough Notice and Report Forms............................................................................ 22

AMS _____________________________________________________________________________________

__________________________________________________________________________ 3

Purpose The purpose of this document is to outline and define AMS program process guidelines and development standards (e.g., coding and naming). (Please be aware, however, that this document will not replicate standards which have been documented elsewhere. In cases where standards have already been created, this document will identify and reference them as appropriate.) It is strongly suggested that all staff (both senior and new hires) follow this document closely. Objective Our objective is to develop programming process guidelines and development standards that will ensure the production of consistently easy to read and maintain programs. Scope As defined by Change Management Project Proposal document: The ABAP Development phase consists of the following steps:

Technical review Coding Technical walkthrough Level 1 testing.

Therefore, this document will adopt the structure of the ABAP Development phase in its review of the process guidelines and development standards. The procedure to manage the complete system change cycle is described in the separate document – Change Management Project proposal. (\\Dams1\vol1\Shared\AMS\AMS Change Management\Change Management Project Proposal.doc).

AMS _____________________________________________________________________________________

__________________________________________________________________________ 4

Technical review It is the responsibility of the Developer to conduct a technical analysis of the business specifications. Appendix G of the Change Management Project Proposal document provides a checklist for Developer technical analysis. Usually, at the end of this process, the business specifications are updated and finalized by the Analyst and technical specifications are prepared by the Developer. Technical specifications should display the input and output of the process and the program logic. Appendix C of this document has details on what to include in the technical specification. If technical specifications are cross-module, they must be signed off by the AMS technical expert from the appropriate module. At the end of this stage the Developer should finalize the technical design of the program and review it with the Analyst. Pre-coding phase Before coding starts, and sometimes as part of technical review, the Developer will:

• Identify similar programs, functions, etc. • Identify tables to be used as a source of the information. • Advise DBAs if new tables or indexes must be created. • Decide whether to copy an existing program or create brand-new. • Define names for new programs, tables, etc. • For update or conversion programs, determine what the best update

method is (call transaction or batch input sessions or inserts). Volume is an important factor in this decision.

• Decide what development class to use (see Naming Standards document).

• If this is a one-time-only program for DIS or RIS modules, then consider saving it in the conversion development class (ZDTP_DIS or ZRTP_RIS).

To identify similar program or functions, one should review the existing functions or reports. Since this should be part of the Analyst’s preliminary investigation, the Analyst should be able to provide this information to the Developer. SAP reports can be found via reporting application-specific trees or area menus.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 5

To identify what tables to be used as a source of the information, the Developer should use following resources:

• ask the Analyst, • for FM reports see FM Data Architecture document, • check SAP logical databases, • debug or SQL-trace SAP programs, • use Repository Browser.

Similar programs or functions should be used to cut down on development time and debugging. Appendix B provides “common” function modules, includes, search helps and views. New development objects could be:

• programs • tables • data elements • domains • structures • lock objects • change documents • function modules • screens • search help • SAPsript layout sets • Includes • Transactions • Number ranges • Security objects • Messages • Area Menus

If new objects are to be developed, one must use naming conventions as described in Naming Standards document (see Appendix A). If there is no convention for the new object, the Developer must contact the Manager of Technical Services. Following should be noted: if SAP code is copied, prefix copied SAP programs with ‘z’ and a letter denoting the module (e.g. ‘ZR_’) -- this will make it easier to identify the module to which the program belongs.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 6

Whenever new tables or indexes are being created, the DBAs and/or the data architect must be notified and consulted. The following information should be provided to them:

• Table name • Indexes • Estimated number of rows • Growth pattern • How often accessed • Buffered or unbuffered.

Note that Z* and Y* tables should be created using data class USER or USER1 and that USER8 and USER9 classes should not be used. For DIS and RIS modules the data model should also be updated when data dictionary changes are made. One of the tasks that developer often has to do is to apply SAP OSS note(s). Note Assistant should be used for implementing SAP notes (transaction code SNOTE). Documentation on Note Assistant can be found here: http://help.sap.com/saphelp_webas610/helpdata/en/bc/3cf839fd35384de10000000a11402f/frameset.htm Coding The SAP system has the following development tools available: ABAP Workbench - to develop reports, programs, functions, tables, screens

and menus ABAP4 Query - to develop reports Report Writer - to develop reports BAPI Development - to develop BAPIs for Web and RFC Web Studio - to develop Web-enabled SAP code SAPscript - to develop printed forms We use some development tools outside of SAP including: Cognos Microsoft Access ABAP Workbench includes: Data Dictionary, ABAP Editor, Function builder, etc. It is strongly recommended to use SAP Reuse Library (transaction SAPLRLB_DISPLAY) and Controls Examples (transaction DWDM) to cut down on development time. Plus check Appendix B – it provides some “common” function modules, includes, search helps and views.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 7

ABAP Workbench General As noted above, sometimes to save time, we copy SAP programs and make changes. If SAP code is to be adopted instead of writing a brand new program, release the new program immediately. Then make changes. This way the SAP original code is preserved and the changes made later can be identified by comparing program versions. If a developer is to write a brand new program, the developer then should use program ZFTEMP in FIS instance as a template. This template clearly divides the program into following sections:

• Tables • Parameters & Select-options • Data declarations • Constants • Initializations • Selection screen verifications • Mainline • Page events • Navigation logic (user commands, line selections) • Forms.

The developer should maintain the same order of the sections across the programs (i.e. data declarations and parameters come before events and events before forms). In the data declaration section, group internal tables together, ranges together and individual fields together. Events should only use performs – no statements. Create a template for online programs. (To be provided later). Data Dictionary • Tables should have create and change date/user/time fields. • Z* and Y* tables should be created using data class USER or USER1.

Classes USER8 and USER9 should not be used by developers. • Create lock objects for tables that will be updated by users.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 8

• Perform impact analysis for any field, data element or domain changes. • Utilize include structures for tables and structures used in screens. This will

minimize maintenance requirements. • Determine if a new table should be buffered or not. Tables that are small,

updated infrequently and accessed frequently are good candidates for full table buffering.

• Consult with the module team, the DBAs and the Data Architect on data dictionary changes and update the data model if applicable.

• Consider using existing data elements and domains when creating new fields. • Insert the client field (mandt) in all tables and indexes. • Insert check tables if applicable (foreign key relationship) when inserting fields

in a table. • Consider whether or not to initialize new fields. Fields not initialized will

contain nulls and initializing a field will trigger a rebuild of the table. • Insert documentation for data elements. • When creating new data elements, consider if creating parameter IDs will be

useful and if change documents are required. • Determine if creating a table maintenance view will suffice when accessing

the table (instead of creating a new screen). • Determine if creating a view will optimize database accesses. • When creating a new table or field, consider what the best techniques are for

presenting pick lists and which technique will promote consistency in presentation to the user (e.g. search helps vs. programmed help lists).

Unix files When designing the program keep in mind following: use valid UNIX file names (e.g. no special characters). Generally speaking, the user should not be allowed to enter the directory names, only the file name itself. We won’t change existing programs, but new programs should be following the requirement. List UNIX directories, their retention period, when they should be used, by which application. Parameters and selection criteria When designing the selection screen, the Developer should assign the following attributes correctly to the selection screen parameters:

• Default values • Search help • PIDs.

Date range is one of the most commonly used parameters. The general rule is that the developer should consider placing edit rules around parameters. In addition, FIS developers should develop the program so that user can enter the date range but does not have to. If a user does enter date range, the program

AMS _____________________________________________________________________________________

__________________________________________________________________________ 9

should accept it. But if a date range is not entered, the program should be able to calculate the date range (as appropriate). This is important for FIS module programs. The rationale is to minimize changes to the program variants maintained by the Production control group. When developing new screen(s), the Developer should look at existing selection screens to maintain the same look and feel. Names Meaningful names for forms and variables must be used. 30 characters are allowed for names of forms and variables. Conventions for programs and table names are described in the Naming Standards document (see Appendix A). If the name of the variable, parameter, table or form is not self-explanatory, a short description must be provided.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 10

Naming standards for variables: S_ = select-options P_ = parameters C_ = constants W_ = global variables L_ = local variables Code for Initializations, Mainline, … The developer should use only PERFORM statements in the mainline of the program to break the program into simple manageable blocks. Principles of structured programming must be in applied in a consistent fashion. Logical blocks of the program must be commented. Code must be indented using ‘Pretty Printer’ option. If a UNIX file is being created by the program, a UNIX file name must follow the naming conventions (TBD). Separate presentation logic from retrieval and update part of the program. Online programming • Ensure consistency in the interface. If applicable, insert the area menu as

includes in the new menu (e.g. usage of zdismenu). • Refer to ergonomic standards from SAP when developing screens. These

standards are available online via transaction BIBS. The corresponding transaction for reports is LIBS.

• Screens should be user-friendly, intuitive and consistent with both Windows and SAP standards.

• Standardize function key (icon) on GUI Status across screens in different modules.

• Display descriptions of coded values on the screen. The coded values may be suppressed when in display mode in certain situations and it will enhance the user-friendliness of the screen.

• Suppress from view any functions that are not available to the user based on their security access. This will enhance the user-friendliness of the screen.

• Ensure consistency with error messages. Standardize when to use information message (I), successful message (S), etc…

• Data that can be updated should have screens with display, change, add and delete modes, with display mode being the default mode. Create appropriate security objects to correspond with each mode.

• Use table locks for any database updates. • Create a prototype if it is possible and elicit feedback from both users and the

team.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 11

• Provide confirmation prompts when deleting records. When deleting a row, consider if the record should be marked as ‘deleted’ (loevm) or physically deleted from the table.

• Provide a warning if the user is in change mode and backs out without saving any changes first (‘are you sure’). Track if any fields are changed when in change mode.

• Ensure that new screens can be accessed via BDC mode. Production Control considerations If there were no records to process, program must return the message: “No records selected”. For potentially long-running jobs, the program must produce message: “# of records processed” every 5,000 records. At the end of the processing, the program must produce the message: “# of records inserted/updated”. Optimization considerations • Use SELECT * with care. Do not use SELECT * when populating internal

tables if NOT all columns are required; only select the necessary columns. • Don’t use columns with low/no selectivity in a where clause. • Don’t index columns with low/no selectivity. Selectivity refers to the number of

distinct values. • To reduce database access by repeated selections, it’s better to scan a table

once into the internal table and then read the internal table using statement READ TABLE … BINARY SEARCH. But be careful and consider resource issues when selecting into an internal table – balance between optimization and memory resources

• Avoid MOVE-CORRESPONDING statements. Instead use MOVE statement and move fields individually or store MOVE statements in the FORM.

• Check SAP performance tips program online (transaction SE30) • Structure of internal table should match the order the fields are returned from

the select statement when selecting into an internal table thereby avoiding usage of the statement ‘into corresponding fields’.

• Avoid nested selects if possible. • Be careful using ‘CHECK’ statements, consider incorporating the selection

criteria into the select statement. • Use the SQL trace and runtime analysis to check the program.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 12

Tips for code changes When making changes to a program, it's common to make a local object, modify the local object and then copy it back to the original program after initial testing is complete. However, it's also important to create a transport as soon as you copy the program. If you don't do this, another programmer can make changes to that program, promote it to AMS and then you find the changes wiped out when the local object is copied back. Lock the original object in FIS so that another developer does not make changes to the program as well. Do a version compare with object in AMS to ensure that another developer does not have any changes that have not yet been promoted to AMS. Remove obsolete commented out code as this will aid in program readability and maintainability. Perform an impact analysis for any common includes, function modules, tables, etc… that may be changed. When modifying ABAP programs, include the change request number and the transport number(s) in the opening comments of the source code. See sample in zfir065a: FISK956693 04/05/05 - Rob - FIS00284 Correct date selection problem Including the change request number means that you don’t have to write a lengthy explanation of the change, plus it will enable us to trace back to the original requirements/specs when questions arise. Producing reports When coding the report program, the Developer should use the corresponding module’s standard report header.

FIS has a standard report header in include program ZFHDPRT. To call the form use form name HEADER_UOFT (this really should be a function module). Example can be found in the program ZFTR001. RIS has the similar standard report header routines in include program ZZRHDPRT. Programs should include a listing of the selection criteria used to generate the report. SAPscript

AMS _____________________________________________________________________________________

__________________________________________________________________________ 13

Try to use text elements as include texts in the form especially if changes in the text are likely to be made somewhat frequently. It may be more feasible that some local text elements can be modified easily by users (e.g. DIS acknowledgement letters). Develop ABAP documentation The Developer is responsible for providing accurate description of the program in the 'Documentation' section of the ABAP Editor. The description must be updated when changes are made to the program. Documentation is to describe what the program does in general terms, input and output of the program. In case of complex selection criteria, provide explanations for selection fields Document program (and selection options if applicable). Also, include comments at top of the source codes the following: 1. When creating a new program, record the Author and date for future

reference or consultation 2. When making changes, the developer name who made the change, the

transport number and the date 3. Comment with transaction code, menu path… (optional) 4. If necessary, documentation notes of some technical aspects of the program In the source codes: 1. Make a brief comment for each block of code. 2. comment with the transport number the lines being changed The idea is to keep high level (general for user) documentation in the ‘Documentation’ section and the technical/detail in the source. The documentation in the ‘Documentation’ section can be extracted from the specifications document. This documentation can refer more to business processes. Variants The Developer is responsible for ensuring test variants are not transported to the production instance.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 14

Production Documentation When moving the program to the production instance, the Developer must update Production documentation (document ZPRODDOC in FIS instance) with specific instructions including the new job name, when to run it, dependencies, etc. For detail instructions see: \\Dams1\vol1\Shared\AMS\TRANSFER\PRODN\ADDJOB.DOC . The Developer should inform Production Control via e-mail about the new job as soon as possible. Security • Consider if the new security object should be transaction or object based. • Determine if access should be table or field level security. • Set levels to represent the various modes of access (e.g. display, change,

add and delete). • Change any existing profiles if required. Area Menus To make it easier for end users to find a report or a function, they are usually organized in the menus by means of area menus or reporting trees. Business specifications should provide a developer an information on how a report or a function will be accessed. It’s responsibility of a developer to solicit the information if it’s not provided. Area menus and reporting trees are controlled by the Technical Team. Therefore a developer should send a request (i.e., e-mail) to them asking to add a new report to the menu, providing them transaction code, navigation path and description (if new or changing).

AMS _____________________________________________________________________________________

__________________________________________________________________________ 15

ABAP4 Query Report Writer/Painter Drilldown reporting Cognos

Will be added later.

AMS _____________________________________________________________________________________

__________________________________________________________________________ 16

Web development Web transaction development When you want ITS files to be managed by the R/3 system so that only a single user is allowed to check files out and modify them, while the others have read only access, you must use ITS Source Control. Procedures to Check-out and Check-in files in FIS Repository: Prerequisite: SAP transaction is tested and transported to all instances Connection (router) to R/3 is open New project: 1. Create project using SAP@Web studio. Service file must begin with Z. Project

naming conventions TBD, template naming conventions TBD. 2. Add project to the FIS Repository using SAP@Web studio. 3. Create transport in FIS instance: transaction SIAC, service Z…. using SAP. 4. Transport (as usual through Production Control). 5. Publish service files and templates to ITS choosing appropriate site: FIS,

QNA, and AMS. Existing project: 1. Open project using SAP@Web studio. 2. Open FIS Repository. Get files, i.e. copy repository files to project. 3. Create transport in FIS instance: transaction SIAC, service. 4. Check-out files into project from Repository. 5. Modify files. 6. Check-in files into repository. 6. Transport (as usual through Production Control) choosing appropriate site:

FIS, QNA, AMS. 7. Publish service files and templates to ITS. Web report development Develop SAP report as usual. Assign authorization group to it. Authorization groups TBD. Release the program to the Web. Call the program from the Web page. Web page design standards are outside of this document scope. Web stat-s To identify what programs are being used by our users, we developed the process to collect statistics. Table ZZSERVICE in FIS is an identification table for the services to functions or reports. The naming convention in the SERVICE field is as follows: 1) The first character is Z, 2) The second character identifies the functional area, F for FIS and R For RIS, 3) The third character identifies if it's for a function (F) or a report

AMS _____________________________________________________________________________________

__________________________________________________________________________ 17

(R). The remaining fields should need no explanation. A developer should update table ZZSERVICE in FIS using transaction SE16, and notify Danny to add the new services to the ITS. Remember to replace your WebRFC service with the one corresponding to the report in order to collect web statistics on that report, otherwise the web report statistics will fall under the service WebRFC. To obtain statistical information run report ZBBR006. Technical Walkthrough See Change Management Proposal document. Example of the form is attached in the Appendix D.

Level 1 Testing See Change Management Proposal document. \\Dams1\vol1\Shared\AMS\AMS Change Management\Change Management Project Proposal.doc

AMS _____________________________________________________________________________________

__________________________________________________________________________ 18

Open issues Issue for upgrade testing: if SAP code was used as a starting point, what program has to be tested in the new upgrade? How to trace programs originated from SAP code? Add them the testing spreadsheet? To the special spreadsheet? Will we have standards for other development tools like Cognos, Microsoft Access. Etc.? Do they have to be part of this document? Should we enforce formal technical walkthrough? One issue that arose from the DIS and RIS teams’ discussion was the handling/removal of programs that are no longer required (this will help with upgrades). DIS and RIS modules have developed in-house configuration. We decided not to include the configuration in this document. Should we make it spin off project?

AMS _____________________________________________________________________________________

__________________________________________________________________________ 19

Appendix A References to documents Naming Standards: Naming standards.doc Change Management Proposal Document: \\Dams1\vol1\Shared\AMS\AMS Change Management\Change Management Project Proposal.doc Transport Procedures: \\Dams1\vol1\Shared\AMS\TRANSFER\OPSREQ\procedure\transport.DOC Production documentation document: \\Dams1\vol1\Shared\AMS\TRANSFER\PRODN\ADDJOB.DOC

AMS _____________________________________________________________________________________

__________________________________________________________________________ 20

Appendix B List of “common” function modules Function groups Function module name 1 ADAT – Calendar

functions

FIRST_DAY_IN_PERIOD_GET LAST_DAY_IN_PERIOD_GET

Input: fiscal year, period and Fiscal year variant Output: date (01MMYYYY)

DATE_TO_PERIOD_CONVERT

Input: Date and Fiscal year variant Output: Fiscal period and year

2 F013 – Accounting programs utility

PERIOD_DAY_DETERMINE

Input: fiscal year, period and Fiscal year variant Output: first and last dates of the month

3 FM2R – Read fund center

FICTR_READ_WITH_FICTR

Input: CF center code Output: CF center name

4 FMAU - FM: Authorizations

FMAU_AUTHORITY_FIFM 5 UOFT-developed ZCAL_RETURN_MONTHN

AME Input: calendar month Output: month name

6 Subroutine to upload data from excel file from local PC

KCD_EXCEL_OLE_TO_INT_CONVERT

EBP/ SU_USER bapi_user_get_detail Get user details

AMS _____________________________________________________________________________________

__________________________________________________________________________ 21

Appendix C Technical Specifications Details Technical specifications should include:

Background

Description of the program (could be from functional specifications) Assumptions Purpose Processing logic

Input Tables and field names Selection screen Transaction screen names and fields

Output Transaction layout SAPscript/report layout Print specifications

Sorting criteria Input Output

Processing Business rules Formulae Exceptions

AMS _____________________________________________________________________________________

__________________________________________________________________________ 22

Appendix D Walkthrough Notice and Report Forms

WALKTHROUGH NOTICE

1. NOTICE OF MEETING SENT TO: ___________________________________ ___________________________________ ___________________________________ ___________________________________ ___________________________________ ___________________________________ AGENDA: ____________________________________________________________________ _____________________________________________________________________________ DATE OF MEETING: __________________ PLACE: _________________________ TIME: __________________ DURATION: _________________________ PRESENTER: __________________ SECRETARY: _________________________ ATTACHED ARE MATERIALS FOR THE WALKTHROUGH. PLEASE BRING MARKED-UP COPIES AND COMMENTS TO THE MEETING. DATE: ____________________ SENT BY: _________________________________ 2. DECISION: ______ REVISE AS STATED AND SCHEDULE ANOTHER WALKTHROUGH. WHEN: ___________________ ______ REVISE AS STATED AND DISTRIBUTED THE CHANGED LISTING TO THE WALKTHROUGH TEAM ______ REVISED AS STATED SIGNATURES OF PARTICIPANTS: ____________________________________ __________________________________ ____________________________________ __________________________________

AMS _____________________________________________________________________________________

__________________________________________________________________________ 23

WALKTHROUGH REPORT

PAGE _____ OF _____

ITEM NO.

DESCRIPTION

INIT

ACTION ITEM