Document The Program Logic or Design

DOCUMENT THE
PROGRAM LOGIC OR
DESIGN
CODING THE PROGRAMS
Portable − The program or software should
run on all computers of same type. By same
type we mean a software developed for
personal computers should run on all PCs. Or
a software for written for tablets should run
on all tablets having the right specifications.
Efficient − A software that does the assigned
tasks quickly is said to be efficient. Code
optimization and memory optimization are
some of the ways of raising program
efficiency.
PROPER IDENTIFIER NAMES
A name that identifies any variable, object,

function, class or method is called
an identifier. Giving proper identifier names
makes a program self-documenting. This
means that name of the object will tell what
it does or what information it stores. Let’s
take an example of this SQL instruction:
• Look at line 10. It tells anyone reading the program that a student’s ID, name and roll number are to be
selected. The names of the variables make this self-explanatory. These are some tips to create proper
identifier names −
• Use language guidelines
• Don’t shy from giving long names to maintain clarity
• Use uppercase and lowercase letters
• Don’t give same name to two identifiers even if the language allows it
• Don’t give same names to more than one identifier even if they have mutually exclusive scope
COMMENTS
In the image above, look at line 8. It tells
the reader that the next few lines of code
will retrieve list of students whose report
card is to be generated. This line is not part
of the code but given only to make the
program more user friendly.
Such an expression that is not compiled but
written as a note or explanation for the
programmer is called a comment. Look at
the comments in the following program
segment. Comments start with //.
• Comments can be inserted as −
• Prologue to the program to explain its objective
• At the beginning and/or end of logical or functional blocks
• Make note about special scenarios or exceptions
• You should avoid adding superfluous comments as that may prove counterproductive by breaking the
flow of code while reading. Compiler may ignore comments and indentations but the reader tends to
read each one of them.
INDENTATION
Distance of text from left or right margin is
called indent. In programs, indentation is
used to separate logically separated
blocks of code. Here’s an example of
indented program segment:
• As you can see, indented program is more understandable. Flow of control from for loop to if and back
to for is very clear. Indentation is especially useful in case of control structures.
• Inserting blank spaces or lines is also part of indentation. Here are some situations where you can and
should use indentation −
• Blank lines between logical or functional blocks of code within the program
• Blank spaces around operators
• Tabs at the beginning of new control structures
STEPS OR PROCEDURES TO DOCUMENT THE
PROGRAM
PROGRAM DOCUMENTATION
• Any written text, illustrations or video that describe a software or program to its users is called program or software document. User can
be anyone from a programmer, system analyst and administrator to end user. At various stages of development multiple documents may
be created for different users. In fact, software documentation is a critical process in the overall software development process.
• In modular programming documentation becomes even more important because different modules of the software are developed by
different teams. If anyone other than the development team wants to or needs to understand a module, good and detailed
documentation will make the task easier.
• These are some guidelines for creating the documents −
• Documentation should be from the point of view of the reader
• Document should be unambiguous
• There should be no repetition
• Industry standards should be used
• Documents should always be updated
• Any outdated document should be phased out after due recording of the phase out
ADVANTAGES OF DOCUMENTATION
• These are some of the advantages of providing program documentation −

• Keeps track of all parts of a software or program
• Maintenance is easier
• Programmers other than the developer can understand all aspects of software
• Improves overall quality of the software
• Assists in user training
• Ensures knowledge de-centralization, cutting costs and effort if people leave the system abruptly
EXAMPLE DOCUMENTS
• A software can have many types of documents associated with it. Some of the important ones include −
• User manual − It describes instructions and procedures for end users to use the different features of the software.
• Operational manual − It lists and describes all the operations being carried out and their inter-dependencies.
• Design Document − It gives an overview of the software and describes design elements in detail. It documents details
like data flow diagrams, entity relationship diagrams, etc.
• Requirements Document − It has a list of all the requirements of the system as well as an analysis of viability of the
requirements. It can have user cases, reallife scenarios, etc.
• Technical Documentation − It is a documentation of actual programming components like algorithms, flowcharts, program
codes, functional modules, etc.
• Testing Document − It records test plan, test cases, validation plan, verification plan, test results, etc. Testing is one phase
of software development that needs intensive documentation.
• List of Known Bugs − Every software has bugs or errors that cannot be removed because either they were discovered very
late or are harmless or will take more effort and time than necessary to rectify. These bugs are listed with program
documentation so that they may be removed at a later date. Also they help the users, implementers and maintenance
people if the bug is activated.
STEPS OR PROCEDURES TO DOCUMENT THE
PROGRAM
• How to plan, write, and deliver technical documentation that works
• Step 1: Do research and create a “Documentation Plan”
• Step 2: Structure and design
• Use templates or “schemas” for consistent on-page design
• Create a simple, logical navigation structure
• Step 3: Create the content
• Start with a draft
• Use the 30/90 rule to get feedback
• Get peer reviews and make revisions
• Edit, edit, and edit some more
• Step 4: Deliver and test
• Step 5: Create a maintenance and update schedule
APPLICATION OF DOCUMENTATION TOOLS
JAVADOC
• Javadoc is a tool which comes with JDK and it is used for generating Java code documentation in HTML
format from Java source code, which requires documentation in a predefined format.
• Following is a simple example where the lines inside /*….*/ are Java multi-line comments. Similarly, the
line which preceeds // is Java single-line comment.
EXAMPLE
You can include required HTML tags inside
the description part. For instance, the
following example makes use of
<h1>....</h1> for heading and <p> has
been used for creating paragraph break −
EXAMPLE
THE JAVADOC TAGS
The javadoc tool recognizes the following
tags −
EXAMPLE
Following program uses few of the
important tags available for documentation
comments. You can make use of other tags
based on your requirements.
The documentation about the AddNum
class will be produced in HTML file
AddNum.html but at the same time a
master file with a name index.html will also
be created.
Now, process the above AddNum.java file
using javadoc utility as follows −
HOW TO WRITE, GENERATE AND USE JAVADOC IN
ECLIPSE?
• To generate Java docs for your project you need to write the required information about the field,
method or class as.
• Then to generate the document follow the steps given in next slide −
STEP 1
Open eclipse, select the option Project
→Generate Javadoc.
STEP 2
Select the javadoc.exe file from the bin
folder of java installation directory,
select the destination folder for the
generated java doc and select Next.
STEP 3
Type the title of the documentation in
the Document title and select the
finish button.
STEP 4
Finally, you can observe the generated doc
files in the generated folder.
You can view the document by opening
the index.html file with the browser.
END

Document The Program Logic or Design

Uploaded by

Copyright:

Available Formats

Document The Program Logic or Design

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Document The Program Logic or Design

Uploaded by

Copyright:

Available Formats

DOCUMENT THE

A name that identifies any variable, object,

• These are some of the advantages of providing program documentation −

You might also like