Documentation 1 Comprehending the present – Investing in the future.

Slides:



Advertisements
Similar presentations
Introducing JavaScript
Advertisements

P5, M1, D1.
Unit 6 Assignment 2 Chris Boardley.
10 Software Engineering Foundations of Computer Science ã Cengage Learning.
Pfleeger and Atlee, Software Engineering: Theory and Practice CS499 Chapter 7 Writing the Programs Shari L. Pfleeger Joann M. Atlee 4 th Edition.
 2006 Pearson Education, Inc. All rights reserved Introduction to Classes and Objects.
Software engineering, program management. The problem  Software is expensive to design! – Industry estimates put software development labor costs at.
1 Introduction to Software Engineering Lecture 42 – Communication Skills.
XP 1 Working with JavaScript Creating a Programmable Web Page for North Pole Novelties Tutorial 10.
CSE1301 Computer Programming: Lecture 13 Documentation.
Program Commenting CS-212 Dick Steflik. Commentary Commentary are pieces of information included in a program’s source files to provide additional information.
Introduction to a Programming Environment
1 ES 314 Advanced Programming Lec 2 Sept 3 Goals: Complete the discussion of problem Review of C++ Object-oriented design Arrays and pointers.
Algorithm Programming Coding Advices Bar-Ilan University תשס " ו by Moshe Fresko.
Software Development, Programming, Testing & Implementation.
System Implementation
Documentation 1. User Documentation 2. Technical Documentation 3. Program Documentation.
Software Re-engineering
CH07: Writing the Programs Does not teach you how to program, but point out some software engineering practices that you should should keep in mind as.
DCT 1123 PROBLEM SOLVING & ALGORITHMS INTRODUCTION TO PROGRAMMING.
Bret Juliano. Introduction What Documentation is Required? – To use a program – To believe a program – To modify a program The Flow-Chart Curse Self-Documenting.
Introduction 01_intro.ppt
Introducing Java.
Systems Analysis And Design © Systems Analysis And Design © V. Rajaraman MODULE 14 CASE TOOLS Learning Units 14.1 CASE tools and their importance 14.2.
1 Requirements Modeling using UML 2.0 Use Cases. 2 Requirements Engineering Software Lifecycle Activities System Engineering Requirements Analysis Software.
Testing. What is Testing? Definition: exercising a program under controlled conditions and verifying the results Purpose is to detect program defects.
1 Shawlands Academy Higher Computing Software Development Unit.
Comp 245 Data Structures Software Engineering. What is Software Engineering? Most students obtain the problem and immediately start coding the solution.
Simple Program Design Third Edition A Step-by-Step Approach
Planning for the Solution
Programming Style and Documentation Objective(s) F To become familiar with Java Style and Documentation Guidelines.
INTRODUCTION TO ALGORITHMS PROGRAMMING. Objectives Give a definition of the term algorithm Describe the various parts of the pseudocode algorithm or algorithm.
1 The Software Development Process  Systems analysis  Systems design  Implementation  Testing  Documentation  Evaluation  Maintenance.
ITEC 370 Lecture 14 Implementation. Review Questions? Draft of design document on F Brief 3-5 minute work update on F (will continue except for mid-term)
Implementation 1. Software Implementation – transforming design into code Requirements Analysis Software Design Implementation Testing Deployment Evolution.
XP Tutorial 10New Perspectives on Creating Web Pages with HTML, XHTML, and XML 1 Working with JavaScript Creating a Programmable Web Page for North Pole.
Software Development Cycle What is Software? Instructions (computer programs) that when executed provide desired function and performance Data structures.
SE: CHAPTER 7 Writing The Program
Sharda University P. K. Mishra (Asst.Prof) Department of Computer Science & Technology Subject Name: Programming Using C Sub Code: CSE-106 Programming.
Software Development Process.  You should already know that any computer system is made up of hardware and software.  The term hardware is fairly easy.
Intermediate 2 Software Development Process. Software You should already know that any computer system is made up of hardware and software. The term hardware.
CPS120: Introduction to Computer Science Functions.
ADTs and C++ Classes Classes and Members Constructors The header file and the implementation file Classes and Parameters Operator Overloading.
C++ Basics C++ is a high-level, general purpose, object-oriented programming language.
The Software Development Process
1 CSCD 326 Data Structures I Software Design. 2 The Software Life Cycle 1. Specification 2. Design 3. Risk Analysis 4. Verification 5. Coding 6. Testing.
Connecting with Computer Science2 Objectives Learn how software engineering is used to create applications Learn some of the different software engineering.
Program Development Cycle
Software Engineering Lecture # 1.
Intermediate 2 Computing Unit 2 - Software Development.
Chapter 7 Implementation. Implementation Approaches F Big bang –Code entire system and test in an unstructured manner F Top-down –Start by implementing.
Design and Planning Or: What’s the next thing we should do for our project?
1 The Software Development Process ► Systems analysis ► Systems design ► Implementation ► Testing ► Documentation ► Evaluation ► Maintenance.
Requirements Management with Use Cases Module 2: Introduction to RMUC Requirements Management with Use Cases Module 2: Introduction to RMUC.
XP Tutorial 10New Perspectives on HTML, XHTML, and DHTML, Comprehensive 1 Working with JavaScript Creating a Programmable Web Page for North Pole Novelties.
Software Design and Development Development Methodoligies Computing Science.
Programming Problem steps must be able to be fully & unambiguously described Problem types; Can be clearly described Cannot be clearly described (e.g.
Software Maintenance PPT By :Dr. R. Mall.
PROGRAMMING METHODOLOGY
Introduction to Classes and Objects
Documentation for Developers
Unit 6 Assignment 2 Chris Boardley.
Chapter 1 Introduction(1.1)
Chapter 7 Writing the Programs Shari L. Pfleeger Joann M. Atlee 4th Edition.
Course: Module: Lesson # & Name Instructional Material 1 of 32 Lesson Delivery Mode: Lesson Duration: Document Name: 1. Professional Diploma in ERP Systems.
Topics Introduction to Value-returning Functions: Generating Random Numbers Writing Your Own Value-Returning Functions The math Module Storing Functions.
Software Requirements Specification (SRS) Template.
Implementation.
CSCE-221 C++ Coding Standard/Guidelines
Software Re-engineering and Reverse Engineering
Presentation transcript:

Documentation 1 Comprehending the present – Investing in the future.

Software Documentation – Happens throughout the software lifecycle. Requirements Analysis Software Design Implementation Testing Deployment Evolution Systems Engineering 2

Types of Documentation For software to be used properly and maintained efficiently, documentation is needed. Usually, three separate sets of documentation are prepared for software: For software to be used properly and maintained efficiently, documentation is needed. Usually, three separate sets of documentation are prepared for software: User documentation, User documentation, System documentation System documentation Technical documentation Technical documentation 3

User Documentation User Guide To run the software system properly, the users need documentation, traditionally called a user guide, that shows how to use the software step by step. User guides usually contains a tutorial section to guide the user through each feature of the software. A good user guide can be a very powerful marketing tool: the importance of user documentation in marketing cannot be over- emphasized. User guides should be written for both the novice and the expert users, and a software system with good user documentation will definitely increase sales. 4

System Documentation System documentation defines the software itself. It should be written so that the software can be maintained and modified by people other than the original developers. System documentation should exist for all phases of system development. 5

Technical Documentation Technical documentation describes the installation and the servicing of the software system. Installation documentation defines how the software should be installed on each computer, for example, servers and clients. Service documentation defines how the system should be maintained and updated if necessary. 6

Summary: Why Documentation ? Provide for communication among team members Act as an information repository to be used by maintenance engineers Provide enough information to management to allow them to perform all program management related activities Describe to users how to operate and administer the system 7

How to Document Code 1) At a minimum: each Source File should have a comment block at the top, with your name, the date, the program filename, and a short description in it. 2) Variables names should be self describing, exceptions being loop counters in for loops, etc. int myWeightInPounds; int timeoutInMsec; 3) Function names should also be self describing CheckForErrors() instead of ErrorCheck(), DumpDataToFile() instead of DataFile(). 4) Use consistent case. camelCaseIsFine 5) Indentation – e.g., you can use 3 spaces, not tabs. 6) No magic numbers – any number other than 0 or 1 should have a constant defined for it. Example: const int squareFeetInSquareYard = 9; 8

How to Document Code 7) Use spaces in all assignment statements, and always use brackets in control / repetition statements for ( int i = 0; i < someConstant; i++ ) { //do something } if ( a == b ) { //do something } This is sometimes referred to as “ One True Brace ” – and it should almost always be used. 8) Use meaningful comments to describe complex situations, avoid unless comments. 9

How to Document Code Summary: Class Comment Blocks Place a header comment block at the top of each class/source file. purpose of the class who wrote it where it fits in the general system when the class was written and revised why the method exists how it uses its data structures and algorithms. Expected input and possible output Expected extensions or revisions 10

How to Document Code Summary: Class Comment Blocks Place a header comment block at the top of each method/module. why the method exists who wrote it when the method was written and revised Where/when the method is called where it fits in the general system how it uses its data structures and algorithms. Expected input and possible output Expected extensions or revisions 11

How to Document Code Summary: Line comments Line comments should be inserted into the source code to explain the objectives of a subset of the instructions comprising a module/method to describe data declarations and blocks of code where the purpose of a statement is not entirely obvious Each major control structure (loop, selection) should be clarified through a line comment 12

Comments and Internal Documentation Line comments are inserted into the source code to explain the objectives of a subset of the instructions comprising a module to describe data declarations and blocks of code where the purpose of a statement is not entirely obvious Each major control structure (loop, selection) should be clarified through a line comment 13

Benefits of Documenting Code Software Engineering is an extraordinarily expensive undertaking. Because of this, it usually requires the code to stay around for a while - How long did Microsoft have to maintain/patch/(defend in court) Windows 95? 14

Benefits of Documenting Code Turnover rate is also very high for Software Engineers – by some estimate as high as 30%. So, even at a good company with a low turnover rate, say, 15%, with 100 software engineers, that ’ s 15 people that need to get up to speed on a project – and 15 people that took all their knowledge about what they coded with them. 15

Benefits of Documenting Code Also note that for the maintenance phase of a project can run 50-80% of the total engineering effort. So it ’ s very important for new programmers to be able to get up to speed in a relatively short amount of time. 16

Summary Understand the problem before you begin building the solution. Follow accepted standards for code/user interface design. Write code that is readable. Separate user interface and data management. Design for the most efficient use of the program by the user. Design code that can be re-used. Keep the program simple Localize input and output 17

The End 18 ______________________ Devon M. Simmonds Computer Science Department University of North Carolina Wilmington ____________________________________________ _________________ Qu es ti ons?