update comments

2017/11/comments/index.html

@@ -181,7 +181,7 @@ <h2 id="code-sucks">Code Sucks</h2>
 <p>But of course, what is clean and obvious and well-written to you, today, while
 the entire project and problem space are fully loaded in your brain&hellip; might not
 be obvious to you, six months from now, or to the poor schmuck that has to debug
-your code with their manager breathing down their neck beacuse the CTO just ran
+your code with their manager breathing down their neck because the CTO just ran
 into a critical bug in prod.</p>
 
 <p>Learning to look at a piece of code that you understand, and trying to figure out
@@ -203,7 +203,7 @@ <h2 id="avoiding-comments-often-makes-your-code-worse">Avoiding Comments Often M
 because you have to make your code clearer to compensate.  I call BS on this as
 well, because I don&rsquo;t think anyone is realistically writing sub-par code and
 then excusing it by slapping a comment on it (aside from <code>// TODO: this is a
-temporary hack, I'll fix it later</code>).  We all write the best code we know howm,
+temporary hack, I'll fix it later</code>).  We all write the best code we know how,
 given the various external constraints (usually time).</p>
 
 <p>The problem with refactoring your code to avoid needing comments is that
@@ -320,6 +320,49 @@ <h2 id="any-comment-is-better-than-no-comment">Any comment is better than no com
 <em>did</em> still round the duration down to the nearest second, so the comment was
 not incorrect per se, it was just misleading.</p>
 
+<h2 id="why">Why?</h2>
+
+<p>The most important comments are the <em>why</em> comments.  Why is the code doing what
+it&rsquo;s doing?  Why must the ID be less than 24 characters?  Why are we hiding this
+option on Linux?  etc.  The reason these are important is that you can&rsquo;t figure
+out the why by looking at the code.  They document lessons learned by the devs,
+outside constraints imposed by the business, other systems, etc. These comments
+are invaluable, and almost impossible to capture in other ways (e.g. function
+names should document what the function does, not why).</p>
+
+<p>Comments that document <em>what</em> the code is doing are less useful, because you can
+generally always figure out what the code is doing, given enough time and
+effort.  The code tells you what it is doing, by definition.  Which is not to
+say that you should never write <em>what</em> comments.  Definitely strive to write the
+clearest code you can, but comments are free, so if you think someone might
+misunderstand some code or otherwise have difficulty knowing what&rsquo;s going on,
+throw in a comment.  At least, it may save them a half hour of puzzling through
+your code, at best it may save them from changing it or using it in incorrect
+ways that cause bugs.</p>
+
+<h2 id="tests">Tests</h2>
+
+<p>Some people think that tests serve as documentation for functions.  And, in a
+way, this is true.  But they&rsquo;re generally very low on my list of effective
+documentation.  Why?  Well, because they have to be incredibly precise, and thus
+they are verbose, and cover a narrow strip of functionality.  Every test tests
+exactly one specific input and one specific output.  For anything other than the
+most simple function, you probably need a bunch of code to set up the inputs and
+construct the outputs.</p>
+
+<p>For much of programming, it&rsquo;s easier to describe briefly what a function does
+than to write code to test what it does.  Often times my tests will be multiple
+times as many lines of code as the function itself&hellip; whereas the doc comment on
+it may only be a few sentences.</p>
+
+<p>In addition, tests only explain the <em>what</em> of a function. What is it supposed to
+do?  They don&rsquo;t explain why, and why is often more important, as stated above.</p>
+
+<p>You should definitely test your code, and tests can be useful in figuring out
+the expected behavior of code in some edge cases&hellip; but if I have to read tests
+to understand your code in general, then that&rsquo;s red flag that you really need to
+write more/better comments.</p>
+
 <h2 id="conclusion">Conclusion</h2>
 
 <p>I feel like the line between what&rsquo;s a useful comment and what&rsquo;s not is difficult

blog/index.xml

@@ -37,7 +37,7 @@ better, written better, it wouldn’t need that comment.</p>
 <p>But of course, what is clean and obvious and well-written to you, today, while
 the entire project and problem space are fully loaded in your brain… might not
 be obvious to you, six months from now, or to the poor schmuck that has to debug
-your code with their manager breathing down their neck beacuse the CTO just ran
+your code with their manager breathing down their neck because the CTO just ran
 into a critical bug in prod.</p>
 
 <p>Learning to look at a piece of code that you understand, and trying to figure out
@@ -59,7 +59,7 @@ thing. Sometimes it can be a huge help.</p>
 because you have to make your code clearer to compensate.  I call BS on this as
 well, because I don’t think anyone is realistically writing sub-par code and
 then excusing it by slapping a comment on it (aside from <code>// TODO: this is a
-temporary hack, I'll fix it later</code>).  We all write the best code we know howm,
+temporary hack, I'll fix it later</code>).  We all write the best code we know how,
 given the various external constraints (usually time).</p>
 
 <p>The problem with refactoring your code to avoid needing comments is that
@@ -176,6 +176,49 @@ updated the function to take a Duration rather than an Int.  Interestingly, it
 <em>did</em> still round the duration down to the nearest second, so the comment was
 not incorrect per se, it was just misleading.</p>
 
+<h2 id="why">Why?</h2>
+
+<p>The most important comments are the <em>why</em> comments.  Why is the code doing what
+it’s doing?  Why must the ID be less than 24 characters?  Why are we hiding this
+option on Linux?  etc.  The reason these are important is that you can’t figure
+out the why by looking at the code.  They document lessons learned by the devs,
+outside constraints imposed by the business, other systems, etc. These comments
+are invaluable, and almost impossible to capture in other ways (e.g. function
+names should document what the function does, not why).</p>
+
+<p>Comments that document <em>what</em> the code is doing are less useful, because you can
+generally always figure out what the code is doing, given enough time and
+effort.  The code tells you what it is doing, by definition.  Which is not to
+say that you should never write <em>what</em> comments.  Definitely strive to write the
+clearest code you can, but comments are free, so if you think someone might
+misunderstand some code or otherwise have difficulty knowing what’s going on,
+throw in a comment.  At least, it may save them a half hour of puzzling through
+your code, at best it may save them from changing it or using it in incorrect
+ways that cause bugs.</p>
+
+<h2 id="tests">Tests</h2>
+
+<p>Some people think that tests serve as documentation for functions.  And, in a
+way, this is true.  But they’re generally very low on my list of effective
+documentation.  Why?  Well, because they have to be incredibly precise, and thus
+they are verbose, and cover a narrow strip of functionality.  Every test tests
+exactly one specific input and one specific output.  For anything other than the
+most simple function, you probably need a bunch of code to set up the inputs and
+construct the outputs.</p>
+
+<p>For much of programming, it’s easier to describe briefly what a function does
+than to write code to test what it does.  Often times my tests will be multiple
+times as many lines of code as the function itself… whereas the doc comment on
+it may only be a few sentences.</p>
+
+<p>In addition, tests only explain the <em>what</em> of a function. What is it supposed to
+do?  They don’t explain why, and why is often more important, as stated above.</p>
+
+<p>You should definitely test your code, and tests can be useful in figuring out
+the expected behavior of code in some edge cases… but if I have to read tests
+to understand your code in general, then that’s red flag that you really need to
+write more/better comments.</p>
+
 <h2 id="conclusion">Conclusion</h2>
 
 <p>I feel like the line between what’s a useful comment and what’s not is difficult

index.html

@@ -194,7 +194,7 @@ <h2 id="code-sucks">Code Sucks</h2>
 <p>But of course, what is clean and obvious and well-written to you, today, while
 the entire project and problem space are fully loaded in your brain&hellip; might not
 be obvious to you, six months from now, or to the poor schmuck that has to debug
-your code with their manager breathing down their neck beacuse the CTO just ran
+your code with their manager breathing down their neck because the CTO just ran
 into a critical bug in prod.</p>
 
 <p>Learning to look at a piece of code that you understand, and trying to figure out
@@ -216,7 +216,7 @@ <h2 id="avoiding-comments-often-makes-your-code-worse">Avoiding Comments Often M
 because you have to make your code clearer to compensate.  I call BS on this as
 well, because I don&rsquo;t think anyone is realistically writing sub-par code and
 then excusing it by slapping a comment on it (aside from <code>// TODO: this is a
-temporary hack, I'll fix it later</code>).  We all write the best code we know howm,
+temporary hack, I'll fix it later</code>).  We all write the best code we know how,
 given the various external constraints (usually time).</p>
 
 <p>The problem with refactoring your code to avoid needing comments is that
@@ -333,6 +333,49 @@ <h2 id="any-comment-is-better-than-no-comment">Any comment is better than no com
 <em>did</em> still round the duration down to the nearest second, so the comment was
 not incorrect per se, it was just misleading.</p>
 
+<h2 id="why">Why?</h2>
+
+<p>The most important comments are the <em>why</em> comments.  Why is the code doing what
+it&rsquo;s doing?  Why must the ID be less than 24 characters?  Why are we hiding this
+option on Linux?  etc.  The reason these are important is that you can&rsquo;t figure
+out the why by looking at the code.  They document lessons learned by the devs,
+outside constraints imposed by the business, other systems, etc. These comments
+are invaluable, and almost impossible to capture in other ways (e.g. function
+names should document what the function does, not why).</p>
+
+<p>Comments that document <em>what</em> the code is doing are less useful, because you can
+generally always figure out what the code is doing, given enough time and
+effort.  The code tells you what it is doing, by definition.  Which is not to
+say that you should never write <em>what</em> comments.  Definitely strive to write the
+clearest code you can, but comments are free, so if you think someone might
+misunderstand some code or otherwise have difficulty knowing what&rsquo;s going on,
+throw in a comment.  At least, it may save them a half hour of puzzling through
+your code, at best it may save them from changing it or using it in incorrect
+ways that cause bugs.</p>
+
+<h2 id="tests">Tests</h2>
+
+<p>Some people think that tests serve as documentation for functions.  And, in a
+way, this is true.  But they&rsquo;re generally very low on my list of effective
+documentation.  Why?  Well, because they have to be incredibly precise, and thus
+they are verbose, and cover a narrow strip of functionality.  Every test tests
+exactly one specific input and one specific output.  For anything other than the
+most simple function, you probably need a bunch of code to set up the inputs and
+construct the outputs.</p>
+
+<p>For much of programming, it&rsquo;s easier to describe briefly what a function does
+than to write code to test what it does.  Often times my tests will be multiple
+times as many lines of code as the function itself&hellip; whereas the doc comment on
+it may only be a few sentences.</p>
+
+<p>In addition, tests only explain the <em>what</em> of a function. What is it supposed to
+do?  They don&rsquo;t explain why, and why is often more important, as stated above.</p>
+
+<p>You should definitely test your code, and tests can be useful in figuring out
+the expected behavior of code in some edge cases&hellip; but if I have to read tests
+to understand your code in general, then that&rsquo;s red flag that you really need to
+write more/better comments.</p>
+
 <h2 id="conclusion">Conclusion</h2>
 
 <p>I feel like the line between what&rsquo;s a useful comment and what&rsquo;s not is difficult

index.xml

@@ -37,7 +37,7 @@ better, written better, it wouldn’t need that comment.</p>
 <p>But of course, what is clean and obvious and well-written to you, today, while
 the entire project and problem space are fully loaded in your brain… might not
 be obvious to you, six months from now, or to the poor schmuck that has to debug
-your code with their manager breathing down their neck beacuse the CTO just ran
+your code with their manager breathing down their neck because the CTO just ran
 into a critical bug in prod.</p>
 
 <p>Learning to look at a piece of code that you understand, and trying to figure out
@@ -59,7 +59,7 @@ thing. Sometimes it can be a huge help.</p>
 because you have to make your code clearer to compensate.  I call BS on this as
 well, because I don’t think anyone is realistically writing sub-par code and
 then excusing it by slapping a comment on it (aside from <code>// TODO: this is a
-temporary hack, I'll fix it later</code>).  We all write the best code we know howm,
+temporary hack, I'll fix it later</code>).  We all write the best code we know how,
 given the various external constraints (usually time).</p>
 
 <p>The problem with refactoring your code to avoid needing comments is that
@@ -176,6 +176,49 @@ updated the function to take a Duration rather than an Int.  Interestingly, it
 <em>did</em> still round the duration down to the nearest second, so the comment was
 not incorrect per se, it was just misleading.</p>
 
+<h2 id="why">Why?</h2>
+
+<p>The most important comments are the <em>why</em> comments.  Why is the code doing what
+it’s doing?  Why must the ID be less than 24 characters?  Why are we hiding this
+option on Linux?  etc.  The reason these are important is that you can’t figure
+out the why by looking at the code.  They document lessons learned by the devs,
+outside constraints imposed by the business, other systems, etc. These comments
+are invaluable, and almost impossible to capture in other ways (e.g. function
+names should document what the function does, not why).</p>
+
+<p>Comments that document <em>what</em> the code is doing are less useful, because you can
+generally always figure out what the code is doing, given enough time and
+effort.  The code tells you what it is doing, by definition.  Which is not to
+say that you should never write <em>what</em> comments.  Definitely strive to write the
+clearest code you can, but comments are free, so if you think someone might
+misunderstand some code or otherwise have difficulty knowing what’s going on,
+throw in a comment.  At least, it may save them a half hour of puzzling through
+your code, at best it may save them from changing it or using it in incorrect
+ways that cause bugs.</p>
+
+<h2 id="tests">Tests</h2>
+
+<p>Some people think that tests serve as documentation for functions.  And, in a
+way, this is true.  But they’re generally very low on my list of effective
+documentation.  Why?  Well, because they have to be incredibly precise, and thus
+they are verbose, and cover a narrow strip of functionality.  Every test tests
+exactly one specific input and one specific output.  For anything other than the
+most simple function, you probably need a bunch of code to set up the inputs and
+construct the outputs.</p>
+
+<p>For much of programming, it’s easier to describe briefly what a function does
+than to write code to test what it does.  Often times my tests will be multiple
+times as many lines of code as the function itself… whereas the doc comment on
+it may only be a few sentences.</p>
+
+<p>In addition, tests only explain the <em>what</em> of a function. What is it supposed to
+do?  They don’t explain why, and why is often more important, as stated above.</p>
+
+<p>You should definitely test your code, and tests can be useful in figuring out
+the expected behavior of code in some edge cases… but if I have to read tests
+to understand your code in general, then that’s red flag that you really need to
+write more/better comments.</p>
+
 <h2 id="conclusion">Conclusion</h2>
 
 <p>I feel like the line between what’s a useful comment and what’s not is difficult