Code Documentation

Code documentation for team collaborating.

Transcript

1. CODE DOCUMENTATION Raka Westu Mogandhi BrownBag Onebit April 1st 2014
2. What is code documentation? Written text besides the code that explain how the code works.
3. 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.
4. What is the purpose? To make developers read their codes much easier
5. Good Documentation should: • Be easy to understand. • Provide valid and working examples. • Provide reference in all classes, method and variables.
6. How to write code documentation? • Write the explanation of how your code works. • Write the example if necessary.
7. 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) {
8. 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. */
9. 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. */
10. Recap • Documentation is important for all team members, especially engineer. • Need to be documented: – All function, classes and variables.