How to write good comments

Download How to write good comments

Post on 18-Jul-2015




3 download

Embed Size (px)


<ul><li><p>@PeterHilton</p><p></p><p>How to write good comments</p></li><li><p>M A N N I N G</p><p>Peter HiltonErik BakkerFrancisco CanedoFOREWORD BY James Ward</p><p>Covers Play 2</p><p>Play for Scala(Manning) </p><p>Peter HiltonErik Bakker Francisco Canedo </p><p></p></li><li><p>The comments problem</p></li><li><p>What are comments for?</p><p>4@PeterHilton </p><p>Comments are usually added with the purpose of making the source code easier to understand </p><p>How best to make use of comments is subject to dispute </p><p></p></li><li><p>What is the problem?</p><p>5@PeterHilton </p><p>Writing comments is harder than writing or coding (because its both) </p><p>Programmers* dont like writing (or talking about writing comments) </p><p>* most programmers</p></li><li><p>Dont write comments!</p><p>6@PeterHilton </p><p>1. Dont say what the code does(because the code already says that) </p><p>2. Dont explain bad code &amp; awkward logic(refactor the code to make it clear) </p><p>3. Dont add too many comments(its messy and theyll get out of date) </p><p>4. Isnt TDD all you need?</p></li><li><p>Bad comments &amp; better code</p></li><li><p>7 sins of bad comments</p><p>8@PeterHilton </p><p>1. Syntax or grammar errors 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</p></li><li><p>Refactoring to avoid the need for comments</p><p>9@PeterHilton </p><p>Better modelling and naming communicate purpose a.k.a intention. Domain-Driven Design is your friend Avoid primitive types in APIs </p><p>Extracting and naming local expressions (and encapsulating logic in functions) makes code its own summary.</p></li><li><p>Adding tests</p><p>10@PeterHilton </p><p>Tests can communicate requirements and intention, and demonstrate using an API but not necessarily </p><p>Tests have a dierent primary purpose and are separate from the code they test and might even be written first</p></li><li><p>Kinds of useful comments</p></li><li><p>Existential angst kitten wants to know why?</p><p>bontempscharly / CC BY 2.0</p></li><li><p>case class Kitten( photo: URL, cutenessScore: Int, age: Duration)</p><p>// Photo of a kitten to console // a trader after a loss, with // cuteness proportional to the // magnitude of the loss. </p><p>def estimateCuteness(kitten: Kitten): Int = ???</p><p>// Returns zero for dead kittens (not cute). // Throws IllegalArgumentException for cats // that are too old to be kittens.</p></li><li><p>Explain why the code exists</p><p>14@PeterHilton </p><p>Good comments answer the why? questions in a way that good code cannot. Even perfect code cannot explain its own existence. </p><p>When should I use this code? What are the alternatives to this code?</p></li><li><p>Pre-conditions, restrictions and limitations</p><p>15@PeterHilton </p><p>When shouldnt I use this code? Explain why pre-conditions and limitations apply. </p><p>Note: programming languages with strong types and pre/post-conditions help here</p></li><li><p>Comments are the introduction</p><p>17@PeterHilton </p><p>Like a book or long document, lengthy code needs an introduction, to explain: purpose - what its for scope - who its for and when it applies summary - what its about </p><p></p></li><li><p>Explain implementation choices</p><p>18@PeterHilton </p><p>Why is that the right functionality? Why is it implemented this way? Why wasnt it done the obvious way? WTF? Exceptions to coding standards often require a comment to say whats going on.</p></li><li><p>/** * @deprecated("Use a kitten instead") */ case class ConsolationPuppy(photo: URL, cuteness: Score, age: Duration) </p><p>/** * We use kittens instead of puppies, * which turn out to be less cute. */ case class ConsolationKitten(photo: URL, cuteness: Score, age: Duration)</p></li><li><p>Comment the code that isnt there</p><p>20@PeterHilton </p><p>Sometimes, you need to talk about code that isnt there any more: Failed approaches Code before optimisation Functionality that became superfluous</p></li><li><p>Concrete API usage examples</p><p>21@PeterHilton </p><p>Using an API can be diicult without having usage examples. This shouldnt apply to application code, because there should always be usages</p></li><li><p>Compensate for dierent levels of fluency in the team</p><p>22@PeterHilton </p><p>Write for your audience, especially on a multi-disciplinary team Dont mix jargon from both problem domain and solution domain New team members shouldnt need to understand everything to read anything</p></li><li><p>Summary of useful comments</p><p>23@PeterHilton </p><p>1. Purpose 2. Scope introduction 3. Summary 4. Limitations 5. Alternatives 6. Examples 7. Explanations for new team members</p><p>}</p></li><li><p>How to write good comments</p></li><li><p>25@PeterHilton </p><p>Not writing any comments at all is giving up. </p></li><li><p>Documentation comments</p><p>26@PeterHilton </p><p>Write a one-sentence documentation comment for each: class public method or function </p><p>Use consistent grammar for comments</p></li><li><p>Discover which comments are hard to write, and why</p><p>27@PeterHilton </p><p>If a comment is easy to write, then that code probably doesnt need a comment. </p><p>How to test code for maintainability: 1. Write a one-sentence comment,</p><p>for every class and method. 2. (there is no 2)</p></li><li><p>Rewriting comments</p><p>28@PeterHilton </p><p>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. </p><p>Include comments in code review. Comments are not separate from code.</p></li><li><p>Deleting comments</p><p>29@PeterHilton </p><p>Improving code includes deleting lines of comments, as well as deleting code. Deleting comments you dont need leaves more room for the ones you do need. </p><p>Refactor the code, then repeat.</p></li><li><p>30@PeterHilton </p><p>A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments. @KevlinHenney</p></li><li><p>Acknowledge that writing (comments) is a specialist skill</p><p>31@PeterHilton </p><p>On a cross-functional development team, not everyone is good at visual design. The same goes for writing about code. </p><p>Work out who is a better writer. Get help with writing comments.</p></li><li><p>Summary</p></li><li><p>How to write good comments (summary)</p><p>33@PeterHilton </p><p>1. Try to write good code first. 2. Try to write a one-sentence comment. 3. Refactor the code (make it easier). 4. Delete unnecessary comments. 5. Rewrite bad comments</p><p>(all good writing requires rewriting) 6. Add detail where needed.</p></li><li><p>34@PeterHilton </p><p>When programming, use the best language for the job. </p><p>Sometimes, its English.</p></li><li><p>@PeterHilton</p><p></p></li></ul>