"Look, I am playing tennis" or how to document your code

Serena Williams playing tennis

Useful? Not really.

Serena Williams playing tennis at the Australian Open 2010

Useful? Yes! Required? Partly! Everybody who cares about tennis knows who she is.  Also, even a small kid can see what she is doing.

Australian Open 2010

Now you are talking

*

Here are 10 quick rules about documenting your code:

1. Say something useful that is not obvious from the code:

var age = 10

//incrementing the age

++age

No kidding?!?

2. Consider the need for a comment a failure in coding. Try to write code that is so obvious that it does not require a comment.

For example, replace

//user's age

var age = 10

with

var userAge = 10

3. Do not comment code to keep it around, just in case. You can use the versioning control system (like Git, or SVN) for that.

4. If you need to comment a piece of code, add the reason for the code to exist. If you need to document how the code is functioning, then you need to refactor the code. 

In other words, document WHY and not HOW the code is working.

5. Document your thought process. Sometimes you need to research a topic and implement the code as a result. This knowledge will not be available to the next developer, so add few lines explaining it.

var fraction, numerator, denominator: Float

. . . 

//for a function, the denominator cannot be 0

if denominator == 0 {

    print("error")

}

6. Feel free to add comments for things that need to be improved but there are not part of your current task.

//TODO: this part need to be refactored as it takes too long time to finish

7. Keep the comments short.

8. Write them in English.

9. Don’t be funny.

Avoid something like:

//destroy the universe

reset = true

or 

// 

// Dear maintainer:

// 

// Once you are done trying to 'optimize' this routine,

// and have realized what a terrible mistake that was,

// please increment the following counter as a warning

// to the next guy:

// 

// total_hours_wasted_here = 42

// 

Actually this was funny! (from here)

10. You are allowed to be an artist, but not in the comments section.

/*

   _     _      _     _      _     _      _     _      _     _      _     _

  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)

   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \      / ._. \

 __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__

(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)

   || M ||      || O ||      || N ||      || K ||      || E ||      || Y ||

 _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._

(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)

 `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'

                 -It's Monkey Business Time! (Version 1.5)

*/

(From link)

11. Do not document the history (that is what source control is for).

/* 

Class created by John Doe on 2015/01/03

Changed but Jimmy to add a new function on 2015/03/02

Refactored by John to remove the function Jimmy added as it is useless on 2015/04/01

Changed by Jimmy to add back the function John removed on 2015/05/04

*/

12. Keep the comments up to date. 

Did you notice the "Here are 10 quick rules..." before rule 1. They were 10 at the beginning, but now they are 12.

Each time you change the code, have a look at the comments around it as a wrong comment can inflict a lot of harm.