Dr Andrew Wallace PhD BEng hons EurIng andrewcsumuse Overview Documentation Javadoc More documentation Documentation Document your program For others For yourself Programs change over time ID: 574694
Download Presentation The PPT/PDF document "Documentation" is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.
Slide1
Documentation
Dr. Andrew Wallace PhD
BEng
(hons)
EurIng
andrew@cs.umu.seSlide2
Overview
Documentation
Javadoc
More documentationSlide3
Documentation
Document your program
For others
For yourself
Programs change over time
Different people can work on itSlide4
Documentation
What is this?
What does it do?
How does it fit in with everything else?
How do I use it?
What are the inputs and outputs?
What assumptions are made?Slide5
Documentation
Comments in the code
//
/* … */
Comments blocks of code
Comments methods
Comment class
Comment packageSlide6
Quiz
Why should you document your code?Slide7
Javadoc
Javadoc is a program for generating documentation form the code
Saves having to view the code
Uses special comments in the code
Javadoc integrated into Eclipse
You need JDK
Project->generate
javadoc
Write the comments within the class file, as method
declarations
and for the class attributes
Outputs HTML filesSlide8
Javadoc
Start a Javadoc comment with /** and end with */
Write a block describing the class etc.
Use keywords that start with @ to add specific details
Can use HTML tags as well like <h1> </h1>Slide9
Javadoc
@
param
– add information on parameters passed to a method
@return – information on the return value
@throws
– throw by the method and whySlide10
Javadoc
/**
This method test IO by calling various IO methods. The method will loop until all test are completed or an error occurs. This method can be used to check a commination link.
@
param
address – a reference to a class containing the address information need to create a connection. The method assumes this is not null.
@return – 0 = all test ok, else a number indicates which test failed.
@throws –
IOException
if there is a problem establishing a connection. The exception contains further information on the problem.
*/
Public
int
TestIO
(
Adress
adress
)
thows
IOException
{Slide11
Javadoc
@author – the original person who wrote the code. At class or interface level
@version – version information in case various version of the software exists.
@see – information on where to find additional information or information on related codeSlide12
Quiz
What is Javadoc?
How do you use it?Slide13
More documentation
What to document?
How to use the code
System description
Algorithm description
Limits
TestingSlide14
More documentation
Using the code
Give example
Compilation
Anything special needed?
Some large projects can become complexSlide15
More documentation
System description
Internal, how it is built up
How do the classes fit in?
Context
References to more information
Javadoc documents
Diagrams
UMLSlide16
More documentation
Algorithm descriptions
Write up how more complex algorithms works such as sorting
Described independent of the code
How was a complex problem solved?Slide17
More documentation
Solution limitations
Limits under test
Limits that effect specification
Nothing is perfect!
How can the limits be avoided?Slide18
More documentation
Test documentation
How to test the code?
Specifications
What can go wrong?
Comment each test case
Why?
Results?
Test plan
When to test?Slide19
More documentation
Coding standards
Indentations
Layout of loops
Brackets
Line lengthSlide20
Quiz
Name three other types of documents (other than source code)?
What do you document in each?Slide21
Questions?