1. Programming Logic and Design Fifth Edition, Comprehensive
Chapter 3
The Program Planning Process: Documentation and Design

2. Objectives Learn about documentation
Learn about the advantages of modularization
Learn how to modularize a program
Declare local and global variables and constants
Programming Logic and Design, Fifth Edition, Comprehensive

3. Objectives (continued)
Understand the mainline logic for many procedural programs
Create hierarchy charts
Understand the features of good program design
Programming Logic and Design, Fifth Edition, Comprehensive

4. Understanding Documentation
All supporting material that goes with a program
Two major categories: for users and for programmers
Usually created by system analysts and/or tech writers
May be printed or electronic (Web or CD)
End users: people who use computer programs
Program Documentation
Internal program documentation: comments within code
External program documentation: supporting paperwork written before programming begins
Programming Logic and Design, Fifth Edition, Comprehensive

5. Output Documentation
Describes the results the user can see when a program is complete
Usually written first
Planning done in consultation with the end user
After desired output is known, programmer can plan processes needed to produce output
Most common types of output:
Printed reports
Screen output
Programming Logic and Design, Fifth Edition, Comprehensive

6. Designing Printed Reports
Printed reports: designed using a print chart
Created using word-processor or design software
Printed reports may contain:
Detail lines: display data details
Heading lines: contain title and column headings
Total (or summary) lines: contain statistics or end of report indicators
Printed reports may contain only summary information
Programming Logic and Design, Fifth Edition, Comprehensive

7. Designing Screen Output
Program output may appear on a monitor screen
In a GUI, user sees a screen and can interact with a mouse or pointing device
Output design resembles a sketch of a screen
GUI designed to allow user to scroll through records
Programming Logic and Design, Fifth Edition, Comprehensive

8. Designing Screen Output (continued)
Figure 3-2 Inventory records displayed in a GUI environment
Figure Inventory records displayed in a running program
Programming Logic and Design, Fifth Edition, Comprehensive

9. Figure 3-6 Inventory file description
Input Documentation
Describes what input is available to produce the output
File description:
Describes data stored in a file
Indicates fields, data types, and lengths
Figure 3-6 Inventory file description
Programming Logic and Design, Fifth Edition, Comprehensive

10. Input Documentation (continued)
Input files organized in different ways
Field may occupy exactly 15 characters for each record
Adding characters to the end of a data field to force it to a specified size is padding the field
Some names might be truncated or abbreviated
Fields may be delimited
Delimiter: character that separates fields
Numeric fields may occupy a specified number of bytes
One program variable for each field
Each data field declared using the data type indicated in the file description
Programming Logic and Design, Fifth Edition, Comprehensive

11. Input Documentation (continued)
Programmers need to know:
Data file name
Data fields and their order within the file
Data types of each field
Figure 3-7 Plan for discounted prices report
Programming Logic and Design, Fifth Edition, Comprehensive

12. Completing the Documentation
Program documentation may contain:
Output design
Input description
Flowcharts
Pseudocode
Program code listing
User documentation may contain:
Manuals
Instructional material
Operating instructions
Programming Logic and Design, Fifth Edition, Comprehensive

13. Completing the Documentation (continued)
User documentation:
Written clearly in plain language
Usually prepared by system analysts and/or tech writers
User documentation usually indicates:
How to prepare input
Output distribution and interpretation
Error message information
Run frequency
Programming Logic and Design, Fifth Edition, Comprehensive

14. Understanding the Advantages of Modularization
Module:
Unit of code that performs one small task
Called a subroutine, procedure, function, or method
Invoke (call) a method is to execute it
Calling method invokes the called method
Program contains unlimited number of methods
Each method can be called unlimited number of times
Programming Logic and Design, Fifth Edition, Comprehensive

15. Understanding the Advantages of Modularization (continued)
Modularization: breaking a large program into modules
Advantages of modularization:
Provides abstraction
Allows multiple programmers to work simultaneously
Allows code reuse
Makes identifying structures easier
Programming Logic and Design, Fifth Edition, Comprehensive

16. Modularization Provides Abstraction
Focuses on important properties while ignoring non-essential details
Avoids low-level details
Makes complex tasks look simple
High-level programming languages allow English-like vocabulary
One statement corresponds to dozens of machine instructions
Modules provide another way to achieve abstraction
Programming Logic and Design, Fifth Edition, Comprehensive

17. Modularization Provides Abstraction (continued)
To-do list with abstraction
Do laundry
Call Aunt Nan
Start term paper
To-do list without abstraction
Pick up laundry basket
Put laundry basket in car
Drive to laundromat
Get out of car with basket
Walk into laundromat
Set basket down
. . .
Programming Logic and Design, Fifth Edition, Comprehensive

18. Modularization Allows Multiple Programmers to Work on a Problem
Commercial programs rarely written by a single programmer
Development time is significantly reduced
Large programming projects can be divided into modules
Modules can be written by different programmers or programming teams
Programming Logic and Design, Fifth Edition, Comprehensive

19. Modularization Allows You to Reuse Your Work
Subroutines that are useful should be used more than once in a program
Example: routine that checks the current date
Instructions placed in their own module are easy to port to other applications
Reusability: the ability to use modules in a variety of applications
Reliability: assurance that a module has been tested and proven to function correctly
Reliable software saves times and money
Programming Logic and Design, Fifth Edition, Comprehensive

20. Modularizing a Program
Most programs contain a main program
Contains the mainline logic
Accesses other modules or subroutines
Rules for naming modules different for every programming language
For this text:
Must be one word
Should be meaningful
Followed by a set of parentheses
Corresponds to module naming in Java, C++, C#
Programming Logic and Design, Fifth Edition, Comprehensive

21. Modularizing a Program (continued)
Table 3-1 Suggested identifiers for a module that calculates an employee’s gross pay
Programming Logic and Design, Fifth Edition, Comprehensive

22. Modularizing a Program (continued)
Calling program (or calling module): one that uses another module
Flowchart symbol for calling a module: rectangle with bar across the top
Flowchart for the module
Start symbol: contains module name
Stop symbol: contains exit or return
When a module is called, logic transfers to the model
When module ends, logic transfers back to the caller
Programming Logic and Design, Fifth Edition, Comprehensive

23. Modularizing a Program (continued)
Figure 3-8 Sample logic
Figure 3-9 Logic from Figure 3-8 using a method
Programming Logic and Design, Fifth Edition, Comprehensive

24. Modularizing a Program (continued)
Figure Logic from Figure 3-9 using two methods
Programming Logic and Design, Fifth Edition, Comprehensive

25. Modularizing a Program (continued)
Method is encapsulated in another method if it is contained in another method
Knowing when to break a module into its own subroutines or submodules is an art
Best practice: place together statements that contribute to one specific task
Functional cohesion: extent to which the statements contribute to the same task
Programming Logic and Design, Fifth Edition, Comprehensive

26. Declaring Local and Global Variables and Constants
Arguments: data items required by a method
Returning a value: data sent back by a method
Method must include:
Header: includes method identifier, other identifying information
Body: contains all statements in the method
Return statement: marks the end of the method
Returns control to the calling method
Data items are visible only within the method in which they are declared
Programming Logic and Design, Fifth Edition, Comprehensive

27. Declaring Local and Global Variables and Constants (continued)
Figure Program that prints a bill using main program that calls nameAndAddress() method
Programming Logic and Design, Fifth Edition, Comprehensive

28. Declaring Local and Global Variables and Constants (continued)
Variables and constants are in scope only within method in which they are declared
Variables and constants are local to the method
Global variables and constants are known to the entire program
Variables and constants declared outside any method are declared at the program level
Reasons to declare variables globally:
Needed in many methods throughout a program
Declare class’s data fields at class level
Programming Logic and Design, Fifth Edition, Comprehensive

29. Declaring Local and Global Variables and Constants (continued)
Declaring global variables and constants: violates encapsulation
Declaring variables and constants within methods: methods are portable
When two or more methods require access to same data, pass the data between methods
Programming Logic and Design, Fifth Edition, Comprehensive

30. Declaring Local and Global Variables and Constants (continued)
Figure Program that prints a bill with some constants declared globally
Programming Logic and Design, Fifth Edition, Comprehensive

31. Understanding the Mainline Logic for Many Procedural Programs
Mainline logic of most procedural programs follows same general structure:
Housekeeping tasks
Variable and constant declarations
Opening files
Main loop tasks
Processes that must occur for every data record
End-of-job tasks
Print footer lines
Close open files
Programming Logic and Design, Fifth Edition, Comprehensive

32. Understanding the Mainline Logic for Many Procedural Programs (continued)
Figure Flowchart and pseudocode of mainline logic for a typical procedural program
Programming Logic and Design, Fifth Edition, Comprehensive

33. Figure 3-17 Sample payroll report
Understanding the Mainline Logic for Many Procedural Programs (continued)
Figure Sample payroll report
Programming Logic and Design, Fifth Edition, Comprehensive

34. Figure 3-18 Logic for payroll report
Understanding the Mainline Logic for Many Procedural Programs (continued)
Figure Logic for payroll report
Programming Logic and Design, Fifth Edition, Comprehensive

35. Creating Hierarchy Charts
Illustrates modules’ relationships
Tells which routines call which other routines
Does not tell when or why the modules are called
Figure Hierarchy chart program in Figure 3-16
Programming Logic and Design, Fifth Edition, Comprehensive

36. Creating Hierarchy Charts (continued)
Figure An organizational hierarchy chart
Programming Logic and Design, Fifth Edition, Comprehensive

37. Creating Hierarchy Charts (continued)
Figure Billing program hierarchy chart
Programming Logic and Design, Fifth Edition, Comprehensive

38. Features of Good Program Design
As programs become larger, need for planning and design increases
Follow expected and clear naming conventions
Store program components in separate files
Strive to design clear statements within your programs and modules
Maintain good programming habits
Programming Logic and Design, Fifth Edition, Comprehensive

39. Following Naming Conventions
Use meaningful names
Self-documenting: program code explains itself to readers without further documentation
Pronounceable names
Use abbreviations carefully
Avoid digits in a name
Separate words in long, multiword variables
Use is or are in names for variables that hold status
Name constants in all uppercase
Programming Logic and Design, Fifth Edition, Comprehensive

40. Storing Program Components in Separate Files
Modularization helps to organize programs
Storing all modules in program file leads to very large program files
Store modules in individual files
Use include, import, copy statement
Share the compiled version of the code, not the source code
Implementation hiding: hiding the details of how a program works
Programming Logic and Design, Fifth Edition, Comprehensive

41. Storing Program Components in Separate Files (continued)
Figure Partial EMPLOYEES file description
Programming Logic and Design, Fifth Edition, Comprehensive

42. Storing Program Components in Separate Files (continued)
Figure Data fields in Figure 3-22 defined in the C++ language
Programming Logic and Design, Fifth Edition, Comprehensive

43. Designing Clear Statements
Select good identifiers
Avoid confusing line breaks
Use temporary variables to clarify long statements
Use constants where appropriate
Programming Logic and Design, Fifth Edition, Comprehensive

44. Avoiding Confusing Line Breaks
Provide enough line breaks for clarity
Figure Code segment with insufficient line breaks
Figure Code segment with appropriate line breaks
Programming Logic and Design, Fifth Edition, Comprehensive

45. Using Temporary Variables to Clarify Long Statements
Use temporary variable (work variable) to hold intermediate mathematical results
Easier to see calculations if computation is broken into individual steps
Figure Two ways of achieving the same salespersonCommission result
Programming Logic and Design, Fifth Edition, Comprehensive

46. Using Constants Where Appropriate
Use named values wherever possible
Easier for readers to understand
When value changes, make one change where constant is defined
Prevents typographical errors
Values of constants will not change during execution of the program
Programming Logic and Design, Fifth Edition, Comprehensive

47. Maintaining Good Programming Habits
Every program will be better if planned before coded
Maintain habit of first drawing flowchart or pseudocode
Walk through program logic on paper (desk-checking) before programming
Think carefully about variable and module names
Design program statements for readability
Programming Logic and Design, Fifth Edition, Comprehensive

48. Maintaining Good Programming Habits (continued)
Figure Program that uses named constants
Programming Logic and Design, Fifth Edition, Comprehensive

49. Summary Documentation: all supporting material for a program
Output documentation: includes report designs
File description: details data types and lengths of each field of data in the file
User documentation: manuals and instructional materials, and operating instructions
Modules: smaller, reasonable units of code that provide reusability
Subroutines, procedures, functions, methods
Programming Logic and Design, Fifth Edition, Comprehensive

50. Summary (continued) Modularization: Modules can call other modules
Provides abstraction
Allows multiple programmers to work on a problem
Makes it easy to reuse work and identify structures
Modules can call other modules
Flowchart symbol is a rectangle with a bar across the top
Variable declarations define the name and type of the data to be stored
Hierarchy chart illustrates modules’ relationships
Programming Logic and Design, Fifth Edition, Comprehensive

51. Summary (continued) Common structure for procedural programs:
Housekeeping tasks
Main loop
End-of-job tasks
Hierarchy chart illustrates modules’ relationships
As programs become larger, need for good planning increases
Store program components in separate files
Use meaningful names
Avoid confusing line breaks, long statements
Programming Logic and Design, Fifth Edition, Comprehensive