Developer's Handbook - Warrant Technologies



WARRANT TECHNOLOGIESPROGRAMMER’S hANDBOOK & cONFIGURATION mANAGEMENT (cm) pLANVersion 1.1February 2nd, 2020Software Engineering ProcessWarrant Technologies, Crane Operations Center115 N. College Ave, Suite 111Bloomington, IN 47404RECORD OF CHANGES*A - ADDED M - MODIFIED D - DELETEDCHANGENUMBERDATENUMBER OF FIGURE, TABLE OR PARAGRAPHA*MDTITLE OR BRIEF DESCRIPTIONCHANGEREQUESTNUMBER06/29/19AllAOriginal Version12/2/20UpdateTABLE OF CONTENTSPartPageContents TOC \o "1-2" \h \z \u SECTION 1. INTRODUCTION PAGEREF _Toc35329091 \h 11.1Scope PAGEREF _Toc35329092 \h 11.2System Overview PAGEREF _Toc35329093 \h 11.3Document Overview PAGEREF _Toc35329094 \h 11.4Architecture PAGEREF _Toc35329095 \h 2SECTION 2. REQUIREMENTS PAGEREF _Toc35329096 \h 32.1Overall Requirements Philosophy PAGEREF _Toc35329097 \h 32.2Requirements Development PAGEREF _Toc35329098 \h 32.3Software Tools PAGEREF _Toc35329099 \h 4SECTION 3. design philosophy PAGEREF _Toc35329100 \h 53.1Purpose PAGEREF _Toc35329101 \h 53.2Life Cycle Models PAGEREF _Toc35329102 \h 73.3Prototyping PAGEREF _Toc35329103 \h 103.4Assembling Reusable Components PAGEREF _Toc35329104 \h 113.5Software Tools PAGEREF _Toc35329105 \h 113.6Programming and Design Development PAGEREF _Toc35329106 \h 123.7Compilers/Cross-Compilers PAGEREF _Toc35329107 \h 123.8Case and Database Management PAGEREF _Toc35329108 \h 123.9Configuration Management, Documentation, and Traceability PAGEREF _Toc35329109 \h 12SECTION 4. Preliminary Design PAGEREF _Toc35329110 \h 174.1Prelininary Design Philosophy PAGEREF _Toc35329111 \h 174.2System Analysis PAGEREF _Toc35329112 \h 18SECTION 5. Detailed Design PAGEREF _Toc35329113 \h 195.1Detailed Design Philosophy PAGEREF _Toc35329114 \h 195.2Documentation of Detailed Design PAGEREF _Toc35329115 \h 22Section 6. Code and Compile PAGEREF _Toc35329116 \h 236.1Coding Tasks PAGEREF _Toc35329117 \h 236.2Directory Organization PAGEREF _Toc35329118 \h 236.3Source Code Organization PAGEREF _Toc35329119 \h 246.4Coding Standards PAGEREF _Toc35329120 \h 256.5Error and Debug Messages in Code PAGEREF _Toc35329121 \h 276.6Machine-Dependent Operations PAGEREF _Toc35329122 \h 27Section 7. Software Testing PAGEREF _Toc35329123 \h 28Section 8. Quality Assurance PAGEREF _Toc35329124 \h 298.1PURPOSE PAGEREF _Toc35329125 \h 298.2TEST PLAN PAGEREF _Toc35329126 \h 298.3APPLICATION MEETS REQUIREMENTS PAGEREF _Toc35329127 \h 298.4BUGS AND TICKETS PAGEREF _Toc35329128 \h 298.5PEER REVIEW PAGEREF _Toc35329129 \h 29Section 9. Configuration Management PAGEREF _Toc35329130 \h 329.1Traceability PAGEREF _Toc35329131 \h 329.2Change Management PAGEREF _Toc35329132 \h 329.3Code Configuration PAGEREF _Toc35329133 \h 33DOCUMENT CHANGE REQUEST FORM (DCR) PAGEREF _Toc35329134 \h 34 This page intentionally left blank.SECTION 1. INTRODUCTION1.1ScopeThis document presents a production methodology that applies to software developed by Warrant Technologies, LLC. It is a guide that describes the tools, the SEE (Software Engineering Environment), design disciplines, development procedures and standards, and the resulting development products. All acronyms and abbreviations used within this document are defined in Appendix A.The guidance contained in this plan will be tailored to meet individual customer requirements. Any new software system benefits from the maximum reuse of preceding systems and code requiring reduced modification and conversion, encapsulation into current designs, and rehosting and integration into current development.Warrant uses the following tools to assist in software development: GitLabEnterprise ArchitectAxure RPMicrosoft SharePoint, Word, Excel, PowerPoint, ProjectThe consistent use of these tools increase productivity; decrease syntactical and logical errors; provide automation in documentation, requirements traceability, rapid prototyping, and CM (configuration management); and facilitate quality through well documented, repeatable processes. The SEE foundation is built on hardware and operating systems that promote open-systems development, time-shared execution, and on-line execution and debugging capabilities. 1.2System OverviewThe mission and system overview for a new system are described in the Project Plan for that system.1.3Document OverviewThis handbook is considered a living document and should be updated as new or different procedures are created. It is designed to give an overall description of a new program and a step-by-step approach on how to generate the program. Maximum use of NDS (non-developmental software), especially commercial of the shelf (COTS) and government-owned software, is in the design. Reuse may require conversion, rehosting, and integration effort of existing software that may not be in the same computer languages and may not have up-to-date documentation while concurrently developing new software; all of which is produced according to standards and guidelines outlined in this handbook. The overall design philosophy embraces many OOD (object-oriented design) principles that isolate and encapsulate software along definable interface boundaries to minimize the rippling effects of change and to promote reusability. This plan recommends the tailoring of this guidance to fit the needs of the project / system. The following paragraphs outline the major sections of this document:Section 1. Introduction. This section describes the basic system and states the development course that the software system engineer has been chartered to perform.Section 2. Requirements. This section describes the philosophies used to establish requirements for a system.Section 3. Design Philosophy. This section describes the philosophies used to develop various parts of the system to meet established milestones. The methodology approach plans, outlined by the system software life cycle model, in this handbook are discussed in terms of software development.Section 4. Preliminary Design. This section outlines the system software design standard. Design standards for products produced in the preliminary design phase for the spiral, waterfall, and agile methodologies are described. Section 5. Detailed Design. This section outlines the detailed design phase and the systems engineering design team workings.Section 6. Code and Compile. This section describes source code organization, directories, makefiles, and general coding standards.Section 7. Unit through Integration Test. This section describes the steps necessary to develop test cases and to perform unit and integration test.Section 8. System Test. This section explains the nature of system testing and the personnel responsible for performing those procedures.Section 9. Quality Assurance. This section describes the QA (quality assurance) procedures to be followed for a project.Section 10. Configuration Management. This section describes the CM procedures to be followed for a project.Section 11. Software Engineering Process Group. This section describes the SEPG (Software Engineering Process Group) activities to be followed.Section 12. Deliveries/Status/Discrepancy Information. This section describes how to generate status and discrepancy reports and what deliverables are associated with a project.Section 13. Documentation. This section describes the HSI (human-system interface), SDD (Software Design Document), and SRS (System Requirements Specification) documentation guidelines.Appendix A. Abbreviations and Acronyms. This appendix lists the acronyms and abbreviations used within this document and their definitions.1.4ArchitectureSystem architectures are defined using DoD Architectural Framework guidance whenever possible. Distributed computer software processing is employed using cloud, hosted server, client, or single board computers (SBC), modular design, encapsulation of interfaces, and data abstraction. New software development adheres to the agreed upon system design and code standards, follows a consistent design discipline, and adheres to the agreed upon design methodology for the subject project. SECTION 2. REQUIREMENTS2.1Overall Requirements PhilosophyHigh-level system requirements are obtained through multiple sources provided by the customer. These sources include: Statement of Work (SoW), Concept Plans, Use Cases, meeting minutes, technical reports, and input from stakeholders. These high-level system requirements must be enhanced, assigned to appropriate CSCI’s (computer software configuration items) as a software / hardware requirement, and documented. Requirements are translated into SW tickets and assigned to a build plan / milestone / epic. This is always a joint Warrant/customer effort. Once a program’s software requirements document is finalized, baselined, and build plan scheduled, changes must be made via CCB (Change Control Board). 2.2Requirements DevelopmentThe system requirements analysis ensures the quality of each requirement as well as determining that allocated requirements are sufficiently developed to allow initiation. This also ensures that the risk of requirements changing is at an acceptably low level. The following tasks comprise the requirements phase of system development.2.2.1Review Requirements AllocationVerify that the requirements which have been allocated are applicable. Identify, track, and resolve any issues and problems with the allocated requirements or configuration item identification. Finally, ensure that the allocated requirements are the basis for follow-on development phases (e.g., preliminary design, detailed design).2.2.2Perform Requirements AnalysisThe reviewed requirements are expounded to identify functional, performance, and nonfunctional (e.g., efficiency, reliability) details. Development constraints such as environmental factors, standards, fault tolerance objectives, hardware characteristics, and language are considered during this phase. If applicable, the interfaces between configuration items and graphical interfaces are identified. Completion of this analysis should ensure traceability, completeness, and consistency of the allocated requirements.During this phase, a more accurate estimate of the amount of work required to implement the task can be developed. The estimate is based on the established procedures for estimating used by the project and is used for establishing a schedule and milestones for the project.2.2.3Generate/Verify/Approve System Requirements ProductsUpon completion of the requirements analysis, a preliminary document detailing the results of the analysis is developed. This may include software requirements specifications, interface requirements specifications, contractor-formatted documents, and tool databases. The intent of this document is to provide the initial framework detailing the implementation of the requirements. The production and review of this document is a joint contractor/customer effort. Review is done in accordance with this handbook. Upon completion of peer review and approval, the preliminary document is baselined and incorporated in a formal requirements document (e.g., Requirements Traceability Matrix (RTM) or Software Requirements Specification (SRS).2.2.4Identify and Implement ChangesAction items, problem change reports, and issues may occur during any project life cycle activity. To ensure that the software requirements will be consistent with the software version in development and test, identify and implement approved changes in accordance with this section. 2.2.5Maintain RecordsEnsure that the software requirements records are prepared and placed in the individual project folder.2.3Software ToolsSome of the software tools that can aid in the requirements phase are as follows:Personal computers / workstations shall be utilized to develop and configuration manage the requirements documentation (GitLab, RTM, SRS type documents, white papers, concept papers, or change requests). Other word processing/documentation tools shall be utilized (e.g., Microsoft Word) to develop and configuration manage the requirements information.Software tools such as GitLab, SharePoint, MS Excel, Word, Project, etc., shall be used to manage development, changes, and traceability for requirements.SECTION 3. design philosophy3.1PurposeThe development of large software systems has become increasingly complex, requiring additional planning in the early stages of development. Figure 3-1 depicts the roles necessary for a successful project.Figure 31. Software Process HYPERLINK \l "_bookmark6" Figure 3-2 depicts the steps required to design, implement, and test a software process. MS Word, Excel, GitLab, and / or Enterprise Architect are used to document the initial stages of design.It is crucial to determine the design philosophy prior to the start of production. This minimizes costly errors late in the project. Listed below are several models available to a project as well as the software tools required to aid the development.Figure 32. Overall Design Process3.2Life Cycle ModelsLife cycle models are networks of life cycle activities. These activities can be (and have been) combined in a great many ways to define the software process for a particular project.This model is the basis for defining, scheduling, and controlling the activities required to develop a software product. It improves communication across the project and is the foundation for project management and the allocation of resources (e.g., staff, equipment, tools, facilities).It provides a common understanding of each group’s rules and responsibilities. It is important that everyone understand not only their own role but the roles of the other people with whom they interface.3.2.1Waterfall ModelThe waterfall model follows the rigid guidelines as set forth in DOD-STD-2167A. This approach imposes requirements that specific documentation be developed prior to progressing to the next phase of development. As noted in Figure 3-3, the downward arrows represent the flow from one phase to another. The reviews associated with each phase are done jointly with the customer to ensure problems are noted and corrected before proceeding to the next phase.Figure 33. Waterfall Software Development Cycle3.2.2Agile ModelThe Agile model was primarily designed to help a project to adapt to change requests quickly. So, the main aim of the Agile model is to facilitate responsiveness to developing requirements while enabling quick project completion. To accomplish this task agility is required. Agility is achieved by fitting the process to the project, removing activities that may not be essential for a specific project. Also, anything that wastes time and/or effort is avoided.In the Agile model, the requirements are decomposed into many small parts that can be incrementally developed. The Agile model adopts Iterative development. Each incremental part is developed over an iteration. Each iteration is intended to be small and easily manageable and that can be completed within, at most, a couple of weeks. Each iteration / sprint is planned, developed and deployed to the customers. Long-term plans are not made. Agile model is the combination of iterative and incremental process models. Steps involve in agile SDLC models are:Requirement gatheringRequirement AnalysisDesignCodingUnit testingIntegration TestingAcceptance testingWith the growth of large, complex systems, the waterfall model was not appropriate. This shortfall led to the inception of exploratory models. Because the developer does not always have sufficient information to complete the requirements at the initial stage, this model allows a certain amount of exploration of information as the project progresses. This is most important for large systems.3.2.6Spiral Model of the Software ProcessThe above models focused on the product and how the production of the product might change through some of the evolutionary process models. One model based on the process that merits discussion is the spiral model. The primary focus of this model is on risk management. By identifying a risk item, actions can be devised to monitor the area in question and avoid the risk. This model begins in the innermost axes, and as time progresses, movement is around and around the spirals. Figure 3-4 depicts the spiral model.Figure 34. Spiral Model of the Software Process3.2.7Object-Oriented DesignOOD is a method of design encompassing the process of object-oriented decomposition and a notation for depicting both logical and physical as well as static and dynamic models of the system under design. OOD leads to an object-oriented decomposition, which is the process of breaking a system into parts, each of which represents some class or object from the problem domain. The support for object-oriented decomposition is what makes OOD quite different from structured design: the former uses class and object abstractions to logically structure systems, and the latter uses algorithmic abstractions.OOA (object-oriented analysis) is a method of analysis that examines requirements from the perspective of the classes and objects found in the vocabulary of the problem domain. The products of OOA can serve as the models for OOD; the products of OOD can then be used in object-oriented programming methods.3.3PrototypingPrototyping is the building of some piece of software system, or some simulation of a software system, in order to verify the requirements, the specification, or the design. Prototypes are used as a means to explore requirements and show the feasibility of a design. Prototypes are used to aid the customer in determining if the product gives them the information they want.Any time you have a specification, you have the potential of prototyping. There are two methods of prototyping. Prototyping can be a throw-away activity and is not developed using all of the standards. This can be a danger because the prototype can become part of the product. This type of prototype is not intended as a deliverable. Warrant Technologies uses Axure for rapid front-end prototyping of this nature.The second method of prototyping is to develop a piece of a fully functional part of the system. If this method is employed, all standards and procedures must be adhered to. If these procedures are not followed, an ill-designed and poorly documented system may be delivered.3.4Assembling Reusable ComponentsThere are several levels of reuse. Reuse involves reusing the code along with its requirement, design, and other documentation and having a generic, or parameterized, way of doing the modification. Also, something can be partly reused but customized slightly.There are different varieties of components that we might consider reusable units. Small components that encapsulate certain complexities are typically reused (e.g., commonly used algorithms). Large components, if they can be reused, include device drivers or software that drives a display.3.5Software ToolsThere are multiple platforms and toolsets that Warrant uses within the development cycle. The sections below outline some of these.3.5.1Operating Systems3.5.1.1Linux Operating System. The Linux OS (Distro) and IDE vary depending on project / customer requirements. Warrant employs Debian and Fedora based distros, which support a number of languages and environments. 3.5.1.2Windows Operating System. The Windows OS and IDE vary depending on project / customer requirements. Warrant uses Windows 10 for Client and a number of Windows Server platforms.3.5.1.3Realtime Operating Systems. Imbedded Realtime OS such as VxWorks, and other Microcontroller OS’s are typically Linux / UNIX-like operating systems that perform in a real-time fashion and are used on development boards, and single board computers (SBC’s). The Realtime OS (Operating System) chosen and version used in the SEE varies depending on project / customer requirements.3.5.2Productivity Enhancement ToolsProductivity enhancement tools automate a programmer’s manual procedures (often with graphical methods) so the procedures can be performed quickly or repeatedly without the errors caused by having to remember numerous details. General information is presented concerning these tools in this section and the following sections. Detailed information concerning the operation of these tools should be found in the appropriate tool’s users’ or programmers’ guide.3.5.2.2Editors. Editors for all platforms include screen editors. Line-oriented editors, which are cumbersome to use, are available but are not discussed in this handbook. IDE’s, Notepad, and other graphical editors provide a more user-friendly environment and are primarily used.3.5.2.3Visual Editor. The editor vi or vim (Visual Editor) is a line editor found available for Linux platforms. The vi editor is powerful yet tedious, requiring the user to remember many single-character commands. Once basic editing is learned, vi is adequate for most editing tasks. This is the preferred editor for Linux operating systems environments. Warrant employs Notepad++ and Microsoft VS Code for editing within Windows based environments.3.5.3Software Debuggers3.5.3.1Program Debugger. Debugger tools vary depending on the IDE being used. Debugging tools are defined at the project level and will be defined in the SDD, Interface level, or within components of the Technical Data Package (TDP).3.6Programming and Design Development The following tools support accelerated programming utilities and rapid prototyping design.3.6.1AxureAxure RP Pro / Team is a wireframing, rapid prototyping, documentation and specification software tool aimed at web, mobile and desktop applications. It offers a What You See is What You Get (WYSIWYG) environment for the creation of a User Interface, as well as light database simulation (via .csv) as well as JavaScript conditional cases for elements (referred to as Widgets by Axure).3.6.2Enterprise ArchitectSparx Systems Enterprise Architect is a visual modeling and design tool based on the OMG UML. The platform supports: the design and construction of software systems; modeling business processes; and modeling industry-based domains.3.7Compilers/Cross-CompilersThere are a number of commercially available compilers available and employed on a per project basis. Commonly employed compilers may include C, C#, C++, Java, Java Script, and Python. They will vary depending on the project and platforms being supported. Warrant employs the Microsoft Visual Studio Code and Eclipse IDEs.3.8Case and Database ManagementWarrant employs multiple types of databases for a diverse group of projects. These range from relational, SQL to No-SQL, object oriented (mongo) databases. Depending on the engine, we use MS SQL Management Studio, PHP MyAdmin, or RoboMongo in our database development.3.9Configuration Management, Documentation, and Traceability3.9.1GitLabGitLab is a tool that provides for managing revisions of source files, maintains a history of changes made, prevents multiple changes to the same file at the same time, provides for separate lines of development for files, provides for merging of revisions and resolution of conflicts, provides release and configuration control, provides an automatic identification of revisions (file name, revision number, date created, author, etc.), and minimizes storage by maintaining only the differences for each revision. GitLab clients communicate with the server to do version control over SSH port 22. We use secure keys for each user that allows push / pull of code per repo. GitLab’s web-based interface provides another mechanism for updating project information. In addition to the version control repo, we use the Issues system for ticketing as described below.The following section outlines the lifecycle process for ticketing.3.9.1.1Ticket GenerationTickets are generated throughout the life of the project for various work items. The following details the creation process and what is needed:Title – Give a descriptive title based on the issue.Description – Provide any data related to the issue. This could be error output, design requirements, or a breakdown of the work approach for the ticket. Include an estimate using the syntax:“/estimate 2h” (This estimates work/ticket for 2 hours)Assignee – Choose who the ticket is assigned to, based on function. If unsure, consult with project owner.Milestone – Choose milestone that the ticket is associated with. If unsure, then it will remain in the backlog until the project owner assigns it.Label – Each project has a set of labels that are unique, except the severity. The following describes these labels:High - Partial loss of functionality with severe impact on the product/project and no workaround currently exists.Moderate - Minor loss of functionality. The result is an inconvenience, which may require a temporary workaround.Low - No loss of service. The result does not prevent software/system operation.Due Date – Select the due date if one has been assigned. If not, consult with the project owner.Figure 3-5 shows an example of the ticket creation.Figure 35. GitLab Ticket Creation3.9.1.2Ticket Updating & ClosingUpdating and closing the ticket as each item is worked is important so that the work performed and time allocated is captured. It also provides a representation of what is being worked on each sprint. The assignee is responsible for updating the ticket for each amount of work they do. This is performed in the description box as follows:Write a good description of the work items that have been performed and the time allocated to the work. Figure 3-6 shows an example.Figure 36. GitLab Ticket DescriptionClicking the “Comment” button updates the ticket and leaves it open.Clicking the “Comment & close issue” button will update and close the issue.3.9.2Enterprise ArchitectThis tool is a document production and desktop publishing system that provides graphics design capability integrated within the text.3.9.3Microsoft WordThis is a document production tool for PC’s. It provides a full range of services (i.e., forms, tables, document templates, graphics).3.9.4Microsoft PowerPointMicrosoft PowerPoint is the Microsoft Office presentation graphics program. PowerPoint helps users present their ideas in a clear and concise manner by providing a set of easy-to-use tools that make presentations look professional. PowerPoint also makes it easier to share and collaborate on presentations over the Web, enabling users to present to and work with others who are geographically dispersed without anyone needing to leave his or her office. In addition, PowerPoint features improved technology for working with diagrams, drawings, pictures, text, and printing.3.9.5SharePointSharePoint is a collaboration and document / content management repository that is hosted or cloud based. SharePoint provides automated CM of documentation in between formal releases.SECTION 4. Preliminary Design4.1Prelininary Design PhilosophyThe preliminary design develops the software architecture to satisfy the allocated requirements. This process may be invoked when it is determined that the requirements are sufficiently developed to allow initiation and the risk of requirements changing is at an acceptably low level.The preliminary design process is broken down into tasks. Each task terminates when the objectives have been completed and the products have been approved.4.1.1Create Preliminary Design (Task 1)The following describes the activities involved in creating the preliminary design:Identify the upper-level components (e.g., CSCI) of the software configuration item in order to model the software architecture. Provide summary descriptions of these upper-level components and summary descriptions of data exchanged among upper-level components.Ensure the preliminary design supports system resource and performance constraints.Address and define the allocation of software to hardware, concurrency, error handling/recovery, size and time estimation, support for special features (e.g., fault tolerance), initialization/recovery, system states, modes, and user interface.For database-oriented systems, create/modify the database design.Identify all NDS (COTS (commercial off-the-shelf) software and reused software) that is to be incorporated into the software architecture. The high-level object model allows for the early identification of rehosted software that can be reused, adapted, or made into global library software.For each software configuration item, represent the software architecture according to the project’s defined design method.In agile environment, part of rapid preliminary design/prototyping may be accomplished using Axure for front-end modeling. 4.1.2Develop Preliminary Design Detail (Task 2)Develop the preliminary design detail as follows:Develop an external interface design for each software component in accordance with the interface requirements defined for the system. Allocate software requirements to each software component.Ensure the preliminary design product satisfies the design criteria associated with the project’s defined design method. The design criteria may include verifiability, adherence to design standards, ease of construction, and simplicity.Ensure that each requirement allocated to the software configuration item is traceable to at least one architectural component of the configuration item.4.1.3Verify/Approve Design Products (Task 3)Verify/approve design products as follows:Verify the project’s defined design methods are being followed.Ensure the preliminary design products are reviewed for correctness and quality.Verify customer reviews are addressed.4.1.4Identify and Implement Changes (Task 4)Identify and implement changes as follows:Identify and record action items, problem change reports, and issues that were determined during preliminary design.Implement changes to the preliminary design using tasks 1 through 3 above.4.1.5Maintain Records (Task 5)Ensure the design records are maintained.4.2System AnalysisDoDAF / UML is used to translate requirements described in the SRS and create a graphical representation of the system architecture. The top-level diagram (context diagram) represents the overall system and the data flows into and out of the system. The second-level diagram represents the functional requirements as specified by the SRS and the data flows between the functional requirements. The third-level diagrams, called DFD’s (data flow diagrams) present the processes, global data stores, and data flows needed to implement the functional requirements.DDE’s (data dictionary elements) are created for each data flow on a third-level DFD. A DDE describes the specific data within a data flow. Review and revision are performed, and once the system analysis model describing the system architecture has been approved, the model is baselined. Future modifications to the system architecture are made to an incremental model based on the original model. The Enterprise Architecture (EA) tool provides the modeling platform typically used to document the system.SECTION 5. Detailed Design5.1Detailed Design PhilosophyOnce the preliminary design models have been approved and baselined, detailed design can begin. Detailed design is the subprocess by which the preliminary design is refined until sufficient detail is documented to implement the design in a programming language. The following is a description of the tasks involved in completing the detailed design process.5.1.1Design Software Components (Task 1)Design the software components as follows:The components that were defined during the preliminary design are decomposed into lower level components. For example, CSCI’s are comprised of CSC’s.Represent these components and their connectivity according to the projects defined design method.Document the component design information.5.1.2Develop Component Design Details (Task 2)Design details are developed by adding/changing the following information:Algorithmic details of each component (CSC).Data representations of each component.Detailed interface (external and internal) to each component.5.1.3Develop Design Products (Task 3)Detailed software design products and interface design products are completed in accordance with the project’s defined design methods.5.1.4Verify Detailed Design Traceability (Task 4)Verify detailed design traceability by ensuring that every software and interface requirement allocated to the configuration item is allocated to at least one design component.5.1.5Verify/Approve Detailed Design Products (Task 5)Verify and approve the detailed design products as follows:Verify the detailed design process methods are being followed.Ensure the detailed design products and recorded information are reviewed for correctness and quality.Verify customer reviews are performed.5.1.6Identify and Implement Change (Task 6)Action items, trouble reports, and issues may occur during any life cycle activity. To ensure detailed design will be consistent with the software version in development or test, approved changes must be incorporated as follows:Identify and record action items, trouble reports, and issues that are discovered during the execution of the detailed design phase.Implement the approved changes by following tasks 1 through 5 above.5.1.7Maintain Records (Task 7)Ensure detailed design records are maintained. Figure 5-1 describes the overall process to be followed for the generation of detailed design.Figure 51. Detailed Design Process5.2Documentation of Detailed Design5.2.1Software Design DocumentEach project has a unique software design document that contains an architectural overview of the system and its components. It is provided in the project site template and developed throughout the life of the system.Section 6. Code and CompileCoding is the subprocess by which the detailed design is transformed into a programming language. This process must be consistent with the detailed design of each software component.6.1Coding TasksThe coding process is divided into tasks that have to be performed to ensure a quality product.6.1.1Review Requirements and Design (Task 1)The software requirements and software design that are applicable to the component are reviewed.6.1.2Code the Components (Task 2)The following activities comprise this task:Write new code as designed.Incorporate code from code generators (e.g., fourth generation language) as designed.Incorporate as designed.Ensure that the code can be properly compiled, which can be performed in unit and built in testing.Ensure the code is consistent with the detailed design, which takes place during peer reviews.Ensure the code meets the project’s standards for coding, which takes place during peer reviews.6.1.3Verify/Approve Code (Task 3)Verify the code in accordance with the peer review process to ensure its correctness and quality.6.1.4Identify and Implement Changes (Task 4)Action items, problem change reports, and issues may occur during any of the project’s life cycle activities. To ensure the code is consistent with the requirements, the following must be performed:Identify and record action items, problem change reports, and issues that are found during the execution of the coding process.Implement the approved changes using tasks 1 through 3 above.6.1.5Maintain Records (Task 5)Ensure coding records (e.g., peer review forms) are prepared and maintained.6.2Directory OrganizationEach project employs a standard directory structure based on the needs of the project. The directory structure frequently takes the shape of a pyramid with the name of the project located at the top of the pyramid. This pyramid or tree structure is based on the UNIX/Linux system file structure. Typically, each subdirectory under the project directory is dedicated to a single subject. This hierarchy is defined by hardware requirements or, more commonly, by CSCI, CSC, and CSU definitions, as noted in Figure 6-1.Figure 61. Hierarchical File StructureGenerally, files (i.e., libraries and headers) that are shared by multiple subdirectories are located together under a COMMON directory structure. No two files or directories in a project are allowed to have the same name. The only exception to this is makefiles. This constraint is a project requirement, not an operating system constraint. Tools that access and utilize the code cannot perform correctly unless this requirement is followed. For example, GitLab combines all files into a single database within the tool; therefore, one file with the same name as another file would overwrite the first file. The only exception is that makefile names are not unique. A common file structure based on UNIX might look like:bin/ binariesdata/ data fileslib/ libraries (may be libs/ as well)log/ program logsobj/ build object filessrc/ source filestmp/ temporary files6.3Source Code OrganizationThe source code must be organized so the core capabilities that are common to any project with a similar display are packaged in a way that could be used (or captured) by other projects with little modification. The basic software mechanisms that drive display, network communications, shared memory, message queues, etc. are isolated from the remainder of the software. Revisions to these core capabilities could, therefore, be made without major impact to other projects that use the software. Any modifications to the core capabilities must be accompanied by an impact review. A new project’s modifications to core capabilities must be kept separate from the captured software, if possible. New files are created to hold the modifications.Additionally, functions are grouped in files according to some common relationship. Where possible, externally referenced data structures have the extern statement placed in a header file. Function prototypes are also placed in a header file.6.4Coding StandardsThe following paragraphs present, in detail, the general layout of the code, common conventions, and rules to follow when coding. Warrant technologies develops in a number of different languages and uses the following conventions in table 6-1 per language in the code structure.Table 61. .NET (C#, VB), Python, Angular, Node Naming ConventionsObject NameNotationLengthPluralPrefixSuffixAbbreviationChar MaskClass namePascalCase128NoNoYesNo[A-z][0-9]Constructor namePascalCase128NoNoYesNo[A-z][0-9]Method namePascalCase128YesNoNoNo[A-z][0-9]Method argumentscamelCase128YesNoNoYes[A-z][0-9]Local variablescamelCase50YesNoNoYes[A-z][0-9]Constants namePascalCase50NoNoNoNo[A-z][0-9]Field namecamelCase50YesNoNoYes[A-z][0-9]Properties namePascalCase50YesNoNoYes[A-z][0-9]Delegate namePascalCase128NoNoYesYes[A-z]Enum type namePascalCase128YesNoNoNo[A-z]Function namecamelCase50YesNoNoNo[A-z][0-9]6.4.1FilesPrograms consist of a collection of files. The code is distributed among the files in a logical fashion. Groups of related functions are contained in the same file. Include files contain one object definition (and related consts, etc.) or a group of declarations and types shared between several files. Object member functions (other than in-line functions) are grouped in a single source file, and the name of the source file relates to the name of the object file.Small files are preferable to large files. If possible, the file should be divided into smaller files where it is practical to do this. Each file consists of specific groups of data that are explained in the following paragraphs.6.4.2Naming ConventionsThe most important rule when naming anything is to be informative. Names such as xyz and ahn convey little information. Names such as curcolor, latitude, and addToList() not only serve as memory locations within a machine but aid human understanding of the software. The compiler translates the code into something the computer can understand; the programmer’s responsibility is to communicate with other people.6.4.3File NamesFile names are chosen to suggest the action of the functions contained within. GitLab requirement exists that no file names may be duplicated within a directory and should be avoided across the project structure. 6.4.4Function NamesFunction names are preferably verb-noun pairs and, with the exception of functions that are constructors and destructors of classes, are also in Camel Case. No underscores are allowed within the function name (e.g., loadData( ) and parseName( )). Where possible, function name size should be kept to 20 characters. Functions that are constructors and destructors of classes follow the naming conventions for classes and therefore begin the first word with a capital letter (e.g., AlertBb.AlertBb and AlertBb.~AlertBb). All other class function names follow the general rules for function names (e.g., AlertBb.createAlertBb and AlertBb.getData).6.4.4.1NOTEClass function names always use the class name prefix.6.4.5Variable NamesIn addition to following the naming constraints in the table above, variables should have a human readable name, and contain a comment describing it6.4.6Class NamesClass names are in Pascal Case, the same as global variables. (e.g., PushBtn, SelectionCmd).6.4.7Typescenter237490enum colors {RED,YELLOW,BLUE}00enum colors {RED,YELLOW,BLUE}Although enum elements are capitalized, the type itself is not capitalized. Class types are capitalized in Pascal Case, the same as global variables. Types that are not part of a class are in Camel Case, the same as local variables. Because types and variables are discernible through context, there should be no confusion.The scoping levels of class types are in the order of private, protected, and public. The default scope for classes is private.6.4.9File CommentsComments in files are used to briefly document a program’s functionality. Comments in source files fall into two categories: general documentation for the file and comments for the source code. File documentation is placed at the beginning of the file and consists of the following:Project:The name of the projectProcess:The name of the process, normally the CSC nameFile:Name of the .c, .h, .C, or .H filePurpose:A general description of the contents of the fileLanguage:Compile languageProgrammer:Author of the fileOrganization:WarrantTechnologiesHost System:The operating system(s) in which the file executesDate Created:Date the original file was generated.Function Descriptions:A brief description of each function declared in theprogram file in the order in which the function appears in the file.6.4.9.1NOTEReplace the label Process with Library for library areas. If a section does not apply to a particular file, N/A (not applicable) follows the section header.6.4.10Shared DataFunctions that are related to or act on the same data are developed in the same file. Declarations of variables that are shared among several functions in a file are placed at the beginning of the file which contains the functions, following any include directives. If data are only used globally within a single file, the data should be declared as static to limit the scope of the data to that file. Static should be used with caution.Declaration of external/global variables and internal/local variables follows scope rules. For example, a variable is not declared globally for ease of access if the variable has limited scope. The extern declaration should be used with caution to prevent programs from having extraneous data connections.6.4.11Main Module StructureThe structure of the main program includes command line argument handling, input message handling, and error handling. Generally, the main program’s size is kept to a minimum. Project leaders are urged to provide a main program template.6.4.12FunctionsA function’s design should have appropriate, easily understood parameters. Functions should be limited in scope and avoid repetitive processing to increase functionality. Functions may or may not have inputs and outputs, which are concisely described. More than four arguments per function are not recommended. A general indication that a function should be split into smaller functions is found when a function exceeds two pages, has excessive nesting or complexity, or uses many internal variables (variables with scope that is less than the entire function). 6.5Error and Debug Messages in CodeDebug messages within code are meant for desk testing and debug before entering a production / release state. Debug and low-level messaging should be transparent to the end user and removed from code when possible.6.6Machine-Dependent OperationsA new user should contact the system administrator to set up the environment for the project. The following describes pertinent information for specific systems.Section 7. Software TestingWarrant Technologies provides a software test plan for each project that encompasses Unit Testing, Integration Testing, and User Acceptance Testing. It provides a framework for associating each requirement to a test or set of tests used to satisfy a requirement. The template can be found in the project’s “Testing” folder, and is tailorable to fit the needs of each project/program.Section 8. Quality Assurance8.1PURPOSE?In order to prevent gaps in functionality and promote better products, Warrant Technologies defines which quality criteria are going to be tested and which quality level the system is required to achieve prior to release.?8.2TEST PLAN?Each product/project will generate a software test plan using Warrant’s defined template for creation and will be reviewed throughout the product/project lifecycle.?8.3APPLICATION MEETS REQUIREMENTS?Each product/project has requirements that are defined from the production instantiation throughout the end of the project.? These are captured within the Requirements Traceability Matrix (RTM).? Each product will have a test-to-requirement mapping within the RTM, and will be tested and findings documented.? This ensures that application functions and features are tested and implemented.?8.4BUGS AND TICKETS?In order to ensure quality of each product, Warrant Technologies mandates that no software bugs of high severity are found open when release is made.?8.5PEER REVIEWThis process outlines the times when code reviews take place, key reviewers, what is analyzed, and way forward.? The peer review process is meant to be an informal, lightweight occurrence when scenarios outlined in the below sections arise.? At the time of this writing, Warrant Technologies uses GitLab for versioning control, tickets, and release of our software products.? The goal of this process is to create better software by reducing number of bugs, aide in resolving merge issues, ensure quality standards are met, and gain useful insight from other team members.???8.5.1Version Control Overview?As part of the versioning control process for our products, Warrant utilizes the Master, Development (Dev), and Feature branches?for development?within our GitLab environment.?We use tags as our product release versioning control.???Tags –?The tag represents a release of the product with a new major or minor version.?This occurs when the product has passed acceptance testing and is created from the master branch.??Master?– This is the?top-level?branch that contains code before it is a?tagged release.? It receives?merged?code from the?Dev?branch after a merge request is approved.?Dev?– The Dev branch culminates?the?majority of?work being built into the product throughout the sprint cycle.? The team commits their code to this branch after passing testing.??Feature –?The feature branch is created from the?Dev?branch and is used when an idea outside of the main backlog is being explored. If code from the backlog is merged, it goes to the?Dev?branch.?The graphic below provides a visual representation of the development branch stages and relationships between branches.8.5.2When do peer reviews occur??Warrant?uses peer reviews in the following scenarios:?Merge requests?–?When a merge request occurs?a peer?review?will?take place.?Tags?– When a tag / release occurs, a peer review will occur.?Upon Developer Request –?Sometimes questions on best practice arise and needs group input.?Project Schedule –?Each project is different and there may be scheduled reviews per requirements.?8.5.3Who takes part??The below identifies who takes part in the peer review and their role within the group:?Lead Developer?– The?lead developer is responsible for organizing the peer review and ensuring artifacts are produced from each review.? Responsible for approving and ensuring clean merges.?Developer Team –?Responsible for collaboration on questions, reviewing code, and giving input to checklist.?Product Owner –?The attendance of the product owner is?optional, but?may be present to help take notes and help tie functionality to requirement.??8.5.4Activities of the Review?During the peer review process the project development team meets to review the following:??Project Code Standards?– Each project will have code standards that need followed.? This could be something as simple as code case structure,?formatting,?and/or?commented code removed.?Readable –?Is the code readable, commented, and/or can a statement be refined or simplified??Duplicated –?Is code duplicated in a module, class, function, or other area??General Questions?– Provides an informal collaborative mechanism to review questions with the code.?Merge conflicts?– Most of the time auto-merge can be executed with very little effort, but occasionally the development team will need to adjudicate issues when development overlap occurs.?Artifacts –?To ensure that meetings are documented, we keep a peer review checklist, containing issues, action items, and participants.???Peer Review Checklist?Project:Date:??Participant List:???Name?Company?Role??????????????Issue List:???Code function in main.js duplicated in form.js??Others???Action Items:???AI #?AI Name?Assigned To?AI Description?AI Due Date?AI Status??001????????002????????????????????Section 9. Configuration ManagementWarrant uses configuration tools GitLab, SharePoint, EA, and RTM to provide the configuration status accounting for a project. As changes are applied to a baseline, they are entered with revision numbers so that previous versions can be recovered if necessary or revisions can be excluded in a release. These products also provide “as-built” records for review and verification.To ensure use of proper CM procedures in a project, project configuration audits are also periodically performed by project management, contractor CM, and customer personnel. These personnel should periodically assess the baselining and CM procedures used by the project to assess baseline integrity, structure, facilities, and completeness of the CM procedure.Data management responsibilities reside with the project manager. It is the project manager’s responsibility to ensure that all CM procedures have been followed and that all data items are reviewed for completeness and adherence to all CM procedures prior to delivery, that status reports are prepared reporting progress or problems for data items, and that schedules and plans are modified as necessary. The project manager ensures that all documentation and baselines are complete and in accordance with tasking and schedule and have been properly QA’d prior to delivery.9.1TraceabilityTraceability between system requirements and the requirements allocated for each CSCI are provided manually and are used to produce the Software Requirements Document, SRS, and /or RTM.9.1.1Requirements TraceabilityThe process of providing traceability from the CSCI requirements to the software units is initiated in the preliminary design phase. The extent of requirements traceability during the spiral development cycle is largely unknown. Ideally, placeholders would act as a trace to link requirements to design (using the RTM (Requirements Traceability Matrix) or produced manually), which would act as a trail for subsequent completion when schedules permit. During the development cycle, this traceability is currently provided manually. 9.1.2Test TraceabilityThe test procedures and results are documented within the Software Test Plan and RTM for each project. At minimum both artifacts provided test cases and result for the unit, integration, and acceptance testing phases.9.2Change Management9.2.1Requirements Change ManagementIf white papers are developed to define requirements, each change is marked and provided to the customer for review approval. Tech questions may also be written to reflect requirement questions and resolutions. Resolution of these questions is the responsibility of the customer. If there is a baselined requirements document for a project, change requests are used to control changes to this document and to implement changes to the program.9.2.2Design Change ManagementChanges to design models are controlled through revisions. Models can be baselined to reflect a baseline delivery change to approved design as indirectly reflected by approved change request.9.3Code Configuration9.3.1GitLabGitLab is Warrant Technologies software version control tool, which is based on the git versioning control system. This tool supports the entire life cycle of a software product. The use of GitLab at the beginning of the design phase ensures that a complete audit trail is available during any stage of development. GitLab is used to configuration manage the code but can be utilized more as procedures and plans are implemented to take advantage of its additional capabilities. This tool also contains a database of all of the change documents related to a product. Life cycles can be assigned for GitLab products. These life cycles define the various stages through which change documents and file changes can go. They consist of such things as peer review, assign work, develop changes, approved, etc. The life cycles are defined and controlled by the GitLab product manager(s) for the project.GitLab is used to control changes that are made to a code base (dev or master branches). The developer is responsible for pushing and pulling their code to development branch often to help ensure productivity is not lost. It is preferred for each developer to generate a keypair and push over SSH. 9.3.2GitLab ProblemsIf problems are encountered using GitLab, they should be coordinated with the System Administrator.DOCUMENT CHANGE REQUEST FORM (DCR)DOCUMENT: DEVELOPER’S HANDBOOK (DevHB)TRACKING NUMBER: _________________ (YYYYMMDD – Process Name)NAME OF PERSON SUBMITTING DCR: _________________________________________ORGANIZATION: _________________________ TELEPHONE: ______________________EMAIL: _____________________________________________________________________DATE: ________________ SHORT TITLE: ________________________________________PROPOSED CHANGE DESCRIPTION: _____________________________________________________________________________________(use section#, figure #, table #, etc.)RATIONALE FOR CHANGE: ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download