Slide 1
Slide 1 text
CODE DOCUMENTATION
Raka Westu Mogandhi
BrownBag Onebit
April 1st 2014
Slide 2
Slide 2 text
What is code documentation?
Written text besides the code that explain how
the code works.
Slide 3
Slide 3 text
Why?
●
Code is hard to read and maintained.
●
Peoples need to know how to use that code.
●
Less time to learn and continuing the project.
Slide 4
Slide 4 text
What is the purpose?
To make developers read their codes much
easier
Slide 5
Slide 5 text
Good Documentation should:
●
Be easy to understand.
●
Provide valid and working examples.
●
Provide reference in all classes, method and
variables.
Slide 6
Slide 6 text
How to write code documentation?
●
Write the explanation of how your code works.
●
Write the example if necessary.
Slide 7
Slide 7 text
Examples.
●
Java (using javadoc) more at
http://www.oracle.com/technetwork/articles/java/index-137868.html
– Class
/**
* Represents wobe product.
* @author rakawm
* @version 0.0.6
*/
public class Product {
– Method
/**
* Return formatted string of DateTime object in UTC timezone.
* Format: dd-MM-yyyy HH:mm or dd-MM-yyyy HH:mm:ss.
* @param dateTime DateTime object.
* @return formatted string of time.
*/
public static String toServerUTC(DateTime dateTime) {
Slide 8
Slide 8 text
Examples (Continued)
●
PHP
/**
* Summary.
*
* Description.
*
* @since x.x.x
* @access (for functions: only use if private)
*
* @see Function/method/class relied on
* @link URL
* @global type $varname Description.
* @global type $varname Description.
*
* @param type $var Description.
* @param type $var Optional. Description.
* @return type Description.
*/
Slide 9
Slide 9 text
Examples (Continued)
●
PHP
/**
* Summary.
*
* Description.
*
* @since x.x.x
* @access (for functions: only use if private)
*
* @see Function/method/class relied on
* @link URL
* @global type $varname Description.
* @global type $varname Description.
*
* @param type $var Description.
* @param type $var Optional. Description.
* @return type Description.
*/
Slide 10
Slide 10 text
Recap
●
Documentation is important for all team
members, especially engineer.
●
Need to be documented:
– All function, classes and variables.