1. Code
Documentation
Adegoke Obasa

2. Programs must be written for people
to read, and for machines to
execute.

3. Why Comment
- They are part of programming
Python - #, C# - // /** */, Lisp - ;;
- Helps explain what unintuitive part of code is
doing.
- Code tells you what, comments tells why.

4. ??
public class FriendlyApp {
public static void main(String[] args) {
String name = "";
if (args.length > 0) {
name = args[0];
}
/* print hello on the screen. */
System.out.println("Hello " + name);
}
}

5. When to
- When doing processing
- API Documentation
- To Track Changes
- To Tag

6. This is better
/* sort the bucket in ascending order. */
while (true) {
while ((bucket[++leftPtr] < bucket[pivot]));
while ((bucket[--rightPtr] > bucket[pivot])
&& (rightPtr > leftPtr));
if (leftPtr < rightPtr) {
/* swap pair found. */
swap(bucket, leftPtr, rightPtr);
} else {
/* no more swap pairs. partition complete. */
swap(bucket, leftPtr, pivot);
break;
}...

7. Using Keywords
- //TODO:
- //FIXME:
- //XXX:
- You can add custom more.

8. Using Keywords
public class TechTalks {
public void sayHello(){
//TODO: Print Hello
}
}

9. Bad Comments
/* This code will get the anagrams of "word".
* To find the anagrams of the word, we have to convert it to lowercase and get rid of
* all trailing whitespaces - this is the format in which we use to store the words
* in the dictionary. We also need to sort
* the characters of the word because we use the sorted characters as a key for the
* anagrams set (All anagrams of a word and the word appear the same when the
* characters have been sorted.) We also
* remove the word from the anagrams set because we do not want it being returned
* with the set as an anagram of itself.
*/
public Set getAnagrams(String word) {
}

10. Commented Code
public static void main(String[] args) throws IOException
{
// while (c != -1) {
// System.out.print((char) c);
// c = in.read();
// }
System.out.println(“Tech Talks”);
}

11. API Documentation
- Not Just REST APIs
- PHPDoc, javadoc etc.
- Use Standard Templates

12. Q & A

13. Further Reading
http://blog.codinghorror.com/code-tells-you-
how-comments-tell-you-why/
..on Software
<http://bodtoki.blogspot.com/2011/02/3-good-
comments-good-code-series.html>

14. Thanks :D
Adegoke Obasa
@goke_epapa