Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Code
Documentation
Adegoke Obasa
Programs must be written for people
to read, and for machines to
execute.
Why Comment
- They are part of programming
Python - #, C# - // /** */, Lisp - ;;
- Helps explain what unintuitive part of ...
??
public class FriendlyApp {
public static void main(String[] args) {
String name = "";
if (args.length > 0) {
name = arg...
When to
- When doing processing
- API Documentation
- To Track Changes
- To Tag
This is better
/* sort the bucket in ascending order. */
while (true) {
while ((bucket[++leftPtr] < bucket[pivot]));
while...
Using Keywords
- //TODO:
- //FIXME:
- //XXX:
- You can add custom more.
Using Keywords
public class TechTalks {
public void sayHello(){
//TODO: Print Hello
}
}
Bad Comments
/* This code will get the anagrams of "word".
* To find the anagrams of the word, we have to convert it to lo...
Commented Code
public static void main(String[] args) throws IOException
{
// while (c != -1) {
// System.out.print((char)...
API Documentation
- Not Just REST APIs
- PHPDoc, javadoc etc.
- Use Standard Templates
Q & A
Further Reading
http://blog.codinghorror.com/code-tells-you-
how-comments-tell-you-why/
..on Software
<http://bodtoki.blog...
Thanks :D
Adegoke Obasa
@goke_epapa
Upcoming SlideShare
Loading in …5
×

Code documentation

455 views

Published on

  • Be the first to comment

Code documentation

  1. 1. Code Documentation Adegoke Obasa
  2. 2. Programs must be written for people to read, and for machines to execute.
  3. 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. 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. 5. When to - When doing processing - API Documentation - To Track Changes - To Tag
  6. 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. 7. Using Keywords - //TODO: - //FIXME: - //XXX: - You can add custom more.
  8. 8. Using Keywords public class TechTalks { public void sayHello(){ //TODO: Print Hello } }
  9. 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. 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. 11. API Documentation - Not Just REST APIs - PHPDoc, javadoc etc. - Use Standard Templates
  12. 12. Q & A
  13. 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. 14. Thanks :D Adegoke Obasa @goke_epapa

×