-
Notifications
You must be signed in to change notification settings - Fork 0
/
03.atom.xml
109 lines (104 loc) · 11.2 KB
/
03.atom.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"><title>Mike Grouchy</title><link href="http://mikegrouchy.com/" rel="alternate"></link><link href="http://mikegrouchy.com/feeds/03.atom.xml" rel="self"></link><id>http://mikegrouchy.com/</id><updated>2013-03-05T00:00:00-05:00</updated><entry><title>Yes, your code does need comments.</title><link href="http://mikegrouchy.com/blog/2013/03/yes-your-code-does-need-comments.html" rel="alternate"></link><updated>2013-03-05T00:00:00-05:00</updated><author><name>Mike Grouchy</name></author><id>tag:mikegrouchy.com,2013-03-05:blog/2013/03/yes-your-code-does-need-comments.html</id><summary type="html"><p>I imagine that this post is going to draw the ire of some. It seems like every
time I mention this on <a href="http://twitter.com/mgrouchy">Twitter</a> or anywhere else
there is always some pushback from people who think that putting comments in
your code is a waste of time.</p>
<p>I think your code needs comments, but so we have a mutual understanding, lets
qualify that.</p>
<div class="codehilite"><pre><span class="k">def</span> <span class="nf">somefunction</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
<span class="c">#add a to b</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span>
<span class="c">#return the result of a + b</span>
<span class="k">return</span> <span class="n">c</span>
</pre></div>
<p>I understand this is a contrived example but this is the comment trap that new
developers get caught in. These types of comments really aren't useful to anyone.
Peppering the code that you just wrote with excessive comments, especially when
it is abundantly clear what the code is doing, is the least useful type of comment
you can write.</p>
<blockquote>
<p>"Code is far better describing what code does than English, so just write clear code"</p>
</blockquote>
<p>This is usually the blowback you get from comments like the ones above. I don't
disagree, programming languages are definitely more precise than English. What I
don't agree with is the idea that if the code is clear and understandable that
comments are unneeded or don't have a place in modern software development.</p>
<p>So knowing this, what kind of comments am I advocating for? I'm advocating for
comments as documentation. Comments that explain what a complex piece of code
does, and most importantly what an entire function or Class does and why they
exist in the first place.</p>
<p>So what is a good example of the kind of documentation I am talking about? I
think <a href="http://twitter.com/zedshaw">Zed Shaw's</a> <a href="http://github.com/zedshaw/lamson">Lamson</a> is a fantastic example of this. Here is a code excerpt from that:</p>
<div class="codehilite"><pre><span class="k">class</span> <span class="nc">Relay</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Used to talk to your &quot;relay server&quot; or smart host, this is probably the most</span>
<span class="sd"> important class in the handlers next to the lamson.routing.Router.</span>
<span class="sd"> It supports a few simple operations for sending mail, replying, and can</span>
<span class="sd"> log the protocol it uses to stderr if you set debug=1 on __init__.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s">&#39;127.0.0.1&#39;</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">25</span><span class="p">,</span> <span class="n">username</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">ssl</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">starttls</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">debug</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> The hostname and port we&#39;re connecting to, and the debug level (default to 0).</span>
<span class="sd"> Optional username and password for smtp authentication.</span>
<span class="sd"> If ssl is True smtplib.SMTP_SSL will be used.</span>
<span class="sd"> If starttls is True (and ssl False), smtp connection will be put in TLS mode.</span>
<span class="sd"> It does the hard work of delivering messages to the relay host.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">hostname</span> <span class="o">=</span> <span class="n">host</span>
<span class="bp">self</span><span class="o">.</span><span class="n">port</span> <span class="o">=</span> <span class="n">port</span>
<span class="bp">self</span><span class="o">.</span><span class="n">debug</span> <span class="o">=</span> <span class="n">debug</span>
<span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span>
<span class="bp">self</span><span class="o">.</span><span class="n">password</span> <span class="o">=</span> <span class="n">password</span>
<span class="bp">self</span><span class="o">.</span><span class="n">ssl</span> <span class="o">=</span> <span class="n">ssl</span>
<span class="bp">self</span><span class="o">.</span><span class="n">starttls</span> <span class="o">=</span> <span class="n">starttls</span>
<span class="o">...</span>
</pre></div>
<p>This code snippet is from <a href="https://github.com/zedshaw/lamson/blob/master/lamson/server.py">https://github.com/zedshaw/lamson/blob/master/lamson/server.py</a>. You can poke around the lamson code and see some good looking
Python code but also some usefully documented code.</p>
<h2>So hold on. Why are we writing comments?</h2>
<p>Why are we writing comments, if you write clean, understandable code? Why do we
need to explain what classes and functions do if the code is "clear" and easy to
understand.</p>
<p>In my opinion, we write comments to capture intent. Comments are the only way
to capture the intent of the code at the time of writing.</p>
<p>Looking at a block of code only allows you to understand the intent of that
particular code at that moment in time which may be very different then the
intent of the code at time of its original writing.</p>
<h2>Writing comments captures intent.</h2>
<p>Writing comments captures the original meaning of the code. Python has <a href="http://www.python.org/dev/peps/pep-0257/">docstrings</a>
for this, other languages have comparable options. What is so good about docstring
type comments? In conjunction with unambiguous class and function names they can
easily describe the original intent of your code.</p>
<p>Why is capturing the original intent of your code important?</p>
<ul>
<li>It allows a developer, at a glance, to look at a piece of code and know why it exists.</li>
<li>It reduces situations where a piece of codes original intent isn't clear then gets modified
and leads to unintended regressions.</li>
<li>It reduces the amount of context a developer must hold his/her mind to solve any particular problem that may be contained in a piece of code.</li>
</ul>
<p><strong>Writing comments to capture intent is like writing tests to prove that your software does what is expected.</strong></p>
<h2>Where do we go from here?</h2>
<p>The first step is to realize that the documentation/comments accompanying a piece
of code can be just important as the code itself and need to be maintained as such.
Just like code can become stale if you don't keep it updated so do comments.
If you update some code you <em>must</em> update the accompanying comments/documentation
or they become useless and can lead to more developer error then not having comments
at all. So we have to treat comments and documentation as first class citizens.</p>
<p>Next we have to agree on what is important to comment on in your code, and how to
structure your code to make your use of comments most effective. Most of this
relies on your own judgement but we can cover most issues with some steadfast rules.</p>
<ol>
<li>Never name your classes and functions ambiguously.</li>
<li>Always use inline comments on code blocks that are complicated or may appear unclear.</li>
<li>Always use descriptive variable names.</li>
<li>Always write comments describing the intent or reason why a piece of code exists.</li>
<li>Always keep comments up to date when editing commented code.</li>
</ol>
<p>As you can see from the points above code as documentation and comments as documentation are not mutually exclusive. Both
are necessary to create readable code that is easily maintained by you and future maintainers.</p>
<blockquote>
<p>If you are interested in keeping up with the latest Python news, discussions,
projects, articles and Jobs you should check out <a href="http://pycoders.com">Pycoder's Weekly</a> the Python
newsletter that I curate.</p>
</blockquote></summary><category term=""></category></entry></feed>