1. Rules for documenting code

2. KISS

3. Keep it short and simple

4. Examples

5. Why do we use
comments?

6. Why do we use
comments?
Comments are failure.

7. Explain Yourself in Code
//
check
if
the
user
is
administrator
if
(user.isRegistered
&&
user.privileges.equals(‘admin’))
{
...
}
vs.
if
(user.isAdmin)
{
...
}

8. What is so bad about
comments?

9. What is so bad about
comments?
They rot.

10. /*
End
slide
*/
Inaccurate comments are worse
than no comments at all.

11. Bad
comments

12. Bad
comments
...most of them.

13. Redundant Comments
/**
*
The
Loader
implementation
with
which
this
Container
is
*
associated.
*/
protected
Loader
loader
=
null;
/**
*
The
Logger
implementation
with
which
this
Container
is
*
associated.
*/
protected
Log
logger
=
null;
/**
*
The
Manager
implementation
with
which
this
Container
is
*
associated.
*/
protected
Manager
manager
=
null;

14. Redundant Comments
protected
Loader
loader
=
null;
protected
Log
logger
=
null;
protected
Manager
manager
=
null;

15. Noise Comments
/**
The
name
*/
private
String
name;
/**
The
version
*/
private
String
version;
/**
The
licence
*/
private
String
licence;

16. Scary Noise Comments
/**
The
name
*/
private
String
name;
/**
The
version
*/
private
String
version;
/**
The
licence
*/
private
String
licence;
/**
The
licence
*/
private
String
info;
/**
The
licence
*/
private
String
help;

17. No Comments
private
String
name;
private
String
version;
private
String
licence;
private
String
info;
private
String
help;

18. Closing Brace Comments
try
{
while
((line
=
in.readLine())
!=
null)
{
...
}
//
while
}
//
try

19. Commented-out Code
public
class
Program
{
static
void
Main(string[]
args)
{
/*
This
block
of
code
is
no
longer
needed
*
because
we
found
out
that
Y2K
was
a
hoax
*
and
our
systems
did
not
roll
over
to
1/1/1900
*/
//DateTime
today
=
DateTime.Today;
//if
(today
==
new
DateTime(1900,
1,
1))
//{
//
today
=
today.AddYears(100);
//
string
message
=
"The
date
has
been
fixed
for
Y2K.";
//
Console.WriteLine(message);
//}
}
}

20. HTML Tags in Comments
/**
*
Task
to
run
fit
tests.
This
task
runs
fitnesse
tests
and
publishes
the
results.
*
*
<pre>
*
Usage:
*
&lt;taskdef
name=&quot;execute-­‐fitnesse-­‐tests&quot;
classname=&quot;fitnesse.ant.ExecuteFitnesseTestsTask&quot;
classpathref=&quot;classpath&quot;
/&gt;
*
OR
*
&lt;taskdef
classpathref=&quot;classpath&quot;
resource=&quot;tasks.properties&quot;
/&gt;
*
*
&lt;execute-­‐fitnesse-­‐tests
suitepage=&quot;FitNesse.SuiteAcceptanceTests&quot;
fitnesseport=&quot;8082&quot;
resultsdir=&quot;${results.dir}&quot;
resultshtmlpage=&quot;fit-­‐results.html&quot;
classpathref=&quot;classpath&quot;
/&gt;
*
</pre>
*/

21. Good
comments

22. Informative Comments
//
format
matched
kk:mm:ss
EEE,
MMM
dd,
yyyy
Pattern
timeMatcher
=
Pattern.compile(
“d*:d*:d*
w*,
w*
d*,
d*”);

23. Warning of Consequences Comments
//
Don’t
run
unless
you
//
have
some
time
to
kill
public
void
_testWithReallyBigFile()
{
writeLinesToFile(100000000);
response.setBody(testFile);
response.readyToSend(this);
String
responseString
=
output.toString();
assertSubString(“Content-­‐Length:
100000000”,
responseString);
assertTrue(bytesSent
>
100000000)
}

24. TODO Comments
//
TODO:
Refactor
this
code

25. TODO Comments
//
TODO:
Refactor
this
code
//
FIXME:
This
won't
work
if
the
file
is
missing.
//
XXX:
This
method
badly
needs
refactoring:
should
switch
by
core
type.

26. Dynamic
comments

27. Tests as Documentation
Unit tests = code level documentation
Behaviour tests = feature documentation

28. Jnario.org

29. Message
Try to write clear self-explanatory code.
Avoid comments if possible.

30. Thanks

31. References
Prowareness blog
http://www.prowareness.com/blog/anti-agile-manisfesto/
Clean Code (A Handbook of Agile Software Craftsmanship)
Robert C. Martin
Jnario
http://jnario.org/