The document outlines best practices for writing comments in code, emphasizing their importance for understanding and maintaining source code. It details the purpose, scope, and common pitfalls of comments, urging programmers to write clear, meaningful remarks that explain the 'why' behind the code. Additionally, it discusses refining comments over time and the significance of good coding practices to minimize the need for excessive commented explanations.

1. @PeterHilton
http://hilton.org.uk/
How to write
good comments

2. # Single-line comments in:
# BASH, CoffeeScript, Perl, PHP, Python, Ruby, YAML,
// C, C++, C#, F#, Java, JavaScript, PHP,
-- Haskell, SQL,
; Assembler, Common Lisp, Emacs Lisp, Logo, Scheme,
% Erlang, PostScript, Prolog, TeX,
' Visual basic,
C FORTRAN,
rem BASIC

3. =begin
Multi-line comments in:
Ruby,
=end
/*
C, C++, Java, JavaScript, PHP
*/
<!--
HTML, XML
-->
###
CoffeeScript
###
http://rigaux.org/language-study/syntax-across-languages.html#VrsCmmnt

4. Code comments

5. What are comments?
Comments are annotations in source code, written
for programmers who maintain the code.
Comments are the only feature common to all*
programming languages.
Comments are amazingly useful, mainly because
we spend more time reading code than writing it.
* general purpose languages 5@PeterHilton •

6. What are comments for?
‘Comments are usually added with the purpose of
making the source code easier to understand, …’
‘How best to make use of comments is subject to
dispute; different commentators have offered
varied and sometimes opposing viewpoints.’
http://en.wikipedia.org/wiki/Comment_(computer_programming) 6@PeterHilton •

7. Who are comments for
Comments are, in the first instance, for yourself.
This includes your future self, who will thank you
for learning to write good comments.
Your colleagues will also thank you, especially if
you’re better at it than them, and write theirs too.
X@PeterHilton •

8. What is the problem?
X@PeterHilton •
Writing comments is harder than
writing or coding
(because it’s both)
Programmers* don’t like writing
(or talking about writing comments)
* most programmers

9. Kinds of useful
comments

10. Existential
angst kitten
wants to
know why?
bontempscharly / CC BY 2.0

11. // Returns zero for dead kittens (not cute).
// Throws IllegalArgumentException for cats
// that are too old to be kittens.
def estimateCuteness(kitten: Kitten): Int = ???
case class Kitten(
photo: URL,
cutenessScore: Int,
age: Duration)
// Photo of a kitten to console
// a trader after a loss, with
// cuteness proportional to the
// magnitude of the loss.
// Returns a cuteness score estimate for
// non-dead kittens less than one year old.

12. class Kitten
attr_accessor :photoUrl
attr_accessor :cutenessScore
attr_accessor :age
def initialize photoUrl, cutenessScore, age
@photoUrl = photoUrl
@cutenessScore = cutenessScore
@age = age
end
end
# Photo of a kitten to console a trader after a loss, with
# cuteness proportional to the magnitude of the loss.

13. Explain why the code exists
Good comments answer the ‘why?’ questions in a
way that good code cannot.
Code cannot explain its own existence.
When should I use this code?
What are the alternatives to this code?
10@PeterHilton •

14. def estimateCuteness kitten
# TODO
end
# Returns an estimated cuteness score for a kitten.
# Returns an estimated cuteness score for a kitten.
# * Returns zero for dead kittens (not cute).
# * Raises an exception for cats that are too old to be kittens.

15. Pre-conditions, restrictions and limitations
Explain pre-conditions, needed for working code,
e.g. valid values
Explain restrictions - when the code won’t work,
e.g. values that are not supported
Tell me when I shouldn’t use this code
Explain why pre-conditions and limitations apply.
12@PeterHilton •

17. Comments are the introduction
Lengthy code needs an introduction, just like a
book or long document, to explain:
purpose - what it’s for
scope - who it’s for and when it applies
summary - what it’s about
http://hilton.org.uk/blog/comments-are-the-introduction 14@PeterHilton •

18. Explain implementation choices
Why is that the right functionality?
Why is it implemented this way?
Why wasn’t it done the obvious way?
Exceptions to coding standards often require a
comment to say what’s going on.
15@PeterHilton •

19. /**
* Deprecated: Use a kitten instead
*/
case class ConsolationPuppy(photo: URL,
cuteness: Score, age: Duration)
/**
* We use kittens instead of puppies,
* which turn out to be less cute.
*/
case class ConsolationKitten(photo: URL,
cuteness: Score, age: Duration)

20. Comment the code that isn’t there
Sometimes, you need to talk about code that isn’t
there any more:
Failed approaches
Code before optimisation
Functionality that became superfluous
X@PeterHilton •

21. Concrete API usage examples
Using an API can be difficult without having usage
examples.
This shouldn’t apply to application code, because
there should always be usages
X@PeterHilton •

22. Compensate for different levels of fluency in the
team
Write for your audience - including the future team,
and especially on a multi-disciplinary team
Don’t mix jargon from different areas - from both
problem domain and solution domain
New team members shouldn’t need to understand
everything to read anything
16@PeterHilton •

23. Summary of useful comments
1. Purpose
2. Scope introduction
3. Summary
4. Limitations
5. Alternatives
6. Examples
7. Explanations for new team members
http://hilton.org.uk/blog/3-kinds-of-good-comments 17@PeterHilton •
}

24. How to write good
comments

25. No comments at all is
giving up.
You can do better than
that.
@PeterHilton • X

26. Documentation comments
Comments can document code’s public interface -
how other programmers will use the code.
Write a one-sentence comment for every:
class and public method (or function)
Use consistent grammar for documentation
comments, e.g. ‘Returns…’
X@PeterHilton •

27. Discover which comments are hard to write,
and why
If a comment is easy to write, then that code
probably doesn’t need a comment (right now).
How to test code for maintainability:
1. Write a one-sentence comment,
for every class and method (or function).
2. (there is no 2)
19@PeterHilton •

28. Rewriting comments
It is unreasonable to expect to write a comment
once and never have to edit it.
Comments require review, rewrites and refactoring,
just like code.
Include comments in code review.
Comments are not separate from code.
20@PeterHilton •

29. Deleting comments
Improving code includes deleting comments,
as well as deleting code.
Delete the comments you don’t need, to
leave more room for the ones you do need.
Refactor the code, then repeat.
http://hilton.org.uk/blog/how-to-comment-code 21@PeterHilton •

30. ‘A common fallacy is to assume authors of
incomprehensible code will somehow be able to
express themselves lucidly and clearly in
comments.’
@KevlinHenney
X@PeterHilton •

31. Acknowledge that writing (comments) is a
specialist skill
On a cross-functional development team, not
everyone is good at visual design.
The same goes for writing about code.
Work out who is a better writer.
Get help with writing comments.
X@PeterHilton •

32. Bad comments

33. Bad code and comments
Comments sometimes compensate for bad code.
Bad code is usually benefits from comments.
Improving bad code usually makes some comments
unnecessary.
(But don’t remove useful comments without
actually improving the code first.)
23@PeterHilton •

34. Refactoring to avoid the need for
comments
X@PeterHilton •
Better modelling and naming communicate
purpose a.k.a intention.
Domain-Driven Design is your friend
Avoid primitive types in APIs
Extracting and naming local expressions
(and encapsulating logic in functions)
makes code its own summary.

35. Adding tests
Tests can communicate requirements and
intention, and demonstrate using an API
… but not necessarily
Tests have a different primary purpose and are
separate from the code they test
… and might even be written first
X@PeterHilton •

36. Don’t write bad comments!
1. Don’t say what the code does
(because the code already says that)
2. Don’t explain bad code & awkward logic
(refactor the code to make it clear)
3. Don’t add too many comments
(it’s messy and they’ll get out of date)
4. Write unit tests instead
24@PeterHilton •

37. 7 sins of bad comments
25@PeterHilton •
1. Errors in syntax or grammar
2. Out-of-date with respect to the code
3. Verbose, taking up too much space
4. Too numerous, adding clutter
5. Duplicating the code
6. Explaining awkward logic
7. Contradicting the code
http://hilton.org.uk/blog/7-ways-to-write-bad-comments

38. Refactoring to avoid the need for comments
Better modelling and naming communicate
purpose a.k.a intention.
Domain-Driven Design is your friend
Avoid primitive types in APIs
Extracting and naming local expressions
(and encapsulating logic in functions)
makes code its own summary. X@PeterHilton •

39. Adding tests
Tests can communicate requirements and
intention, and demonstrate using an API
… but not necessarily
Tests have a different primary purpose and are
separate from the code they test
… and might even be written first
X@PeterHilton •

40. Summary

41. Comments are hard
Not everyone is good at writing, and technical
writing is a specialism like user interface design.
Writing comments is harder than writing or coding
(because it includes both).
Programmers* don’t like writing, which includes
writing comments.
* some programmers 27@PeterHilton •

42. How to write good comments (summary)
1. Try to write good code first.
2. Write a one-sentence comment.
3. Refactor the code (make it easier to understand).
4. Delete unnecessary comments.
5. Rewrite bad comments
(all good writing requires rewriting)
6. Add detail where needed.
7. Do it for your future self. 28@PeterHilton •

43. When programming,
use the best language
for the job.
Sometimes, it’s English.
@PeterHilton • X

44. @PeterHilton
http://hilton.org.uk/