How to write good comments

4,315 views

Published on

Bad comments are such a big problem, that most discussion on the subject never gets past how not to write bad comments. No wonder so many programmers admit defeat and adopt a policy of writing no comments at all.

This talk goes beyond bad comments to discover different kinds of good comments that are worth having, no matter how beautiful and perfect the code is.

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,315
On SlideShare
0
From Embeds
0
Number of Embeds
276
Actions
Shares
0
Downloads
11
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

How to write good comments

  1. 1. @PeterHilton http://hilton.org.uk/ How to write good comments
  2. 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. 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. 4. Code comments
  5. 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. 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. 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. 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. 9. Kinds of useful comments
  10. 10. Existential angst kitten wants to know why? bontempscharly / CC BY 2.0
  11. 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. 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. 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. 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. 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 •
  16. 16. 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 •
  17. 17. 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 •
  18. 18. /** * 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)
  19. 19. 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 •
  20. 20. 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 •
  21. 21. 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 •
  22. 22. 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 • }
  23. 23. How to write good comments
  24. 24. No comments at all is giving up. You can do better than that. @PeterHilton • X
  25. 25. 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 •
  26. 26. 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 •
  27. 27. 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 •
  28. 28. 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 •
  29. 29. ‘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 •
  30. 30. 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 •
  31. 31. Bad comments
  32. 32. 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 •
  33. 33. 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.
  34. 34. 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 •
  35. 35. 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 •
  36. 36. 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
  37. 37. 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 •
  38. 38. 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 •
  39. 39. Summary
  40. 40. 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 •
  41. 41. 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 •
  42. 42. When programming, use the best language for the job. Sometimes, it’s English. @PeterHilton • X
  43. 43. @PeterHilton http://hilton.org.uk/

×