zaine/org_web
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Auto-publish on Fri 26 Sep 15:56:57 BST 2025

Browse Source
This commit is contained in:
Zaine Arch
2025-09-26 15:56:57 +01:00
parent a34379b38e
commit fb120bc50a
35 changed files with 397 additions and 1502 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
output/posts/clean-code/clean-code-chapter-4.html
View File

@@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2025-08-28 Thu 17:45 -->
<!-- 2025-09-26 Fri 15:56 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Clean Code: Chapter 4 Notes</title>
@@ -224,34 +224,34 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orgf38a65c">Chapter 4: Comments</a>
<li><a href="#org3b3a86a">Chapter 4: Comments</a>
<ul>
<li><a href="#orgccbc8a0">Comments Do Not Make Up for Bad Code</a></li>
<li><a href="#orgf7cdf31">Good Comments</a>
<li><a href="#org563b20a">Comments Do Not Make Up for Bad Code</a></li>
<li><a href="#orgbb15258">Good Comments</a>
<ul>
<li><a href="#org9362690">Legal Comments</a></li>
<li><a href="#orgea06608">Informative Comments</a></li>
<li><a href="#org9a8cff9">Explanation of Intent</a></li>
<li><a href="#org756e85b">Clarification</a></li>
<li><a href="#orge9e3aea">Warning of Consequences</a></li>
<li><a href="#orgda7a8c2"><span class="todo TODO">TODO</span> Comments</a></li>
<li><a href="#org7ab6062">Amplification</a></li>
<li><a href="#org4e714d5">Javadocs in Public APIs</a></li>
<li><a href="#orgc8daf95">Legal Comments</a></li>
<li><a href="#org5f86e2c">Informative Comments</a></li>
<li><a href="#org9c9a43a">Explanation of Intent</a></li>
<li><a href="#org132954b">Clarification</a></li>
<li><a href="#org2bc9356">Warning of Consequences</a></li>
<li><a href="#org29e7534"><span class="todo TODO">TODO</span> Comments</a></li>
<li><a href="#org8f96c61">Amplification</a></li>
<li><a href="#orgf0eacd6">Javadocs in Public APIs</a></li>
</ul>
</li>
<li><a href="#orgad7568e">Bad Comments</a>
<li><a href="#orgeceeef2">Bad Comments</a>
<ul>
<li><a href="#org4e4984e">Don’t Use a Comment When You Can Use a Function or Variable</a></li>
<li><a href="#orgaf4e48a">Position Markers</a></li>
<li><a href="#orgb51d8f6">Closing Brace Comments</a></li>
<li><a href="#org45f7fed">Attributions and Bylines</a></li>
<li><a href="#orgd72549e">Commented Out Code</a></li>
<li><a href="#orga4d406b">HTML Comments</a></li>
<li><a href="#org191c38a">Nonlocal Information</a></li>
<li><a href="#org66a46c7">Too Much Information</a></li>
<li><a href="#org1de4858">Inobvious Connection</a></li>
<li><a href="#orgec05bc1">Function Headers</a></li>
<li><a href="#org9f353fd">Javadocs in Nonpublic Code</a></li>
<li><a href="#org8948eeb">Don’t Use a Comment When You Can Use a Function or Variable</a></li>
<li><a href="#org9dd57c3">Position Markers</a></li>
<li><a href="#org27ce2f1">Closing Brace Comments</a></li>
<li><a href="#orgec579fa">Attributions and Bylines</a></li>
<li><a href="#org5ae47be">Commented Out Code</a></li>
<li><a href="#orgfe581e3">HTML Comments</a></li>
<li><a href="#org458bb98">Nonlocal Information</a></li>
<li><a href="#org6d8a526">Too Much Information</a></li>
<li><a href="#org99e4520">Inobvious Connection</a></li>
<li><a href="#org856f330">Function Headers</a></li>
<li><a href="#org080d921">Javadocs in Nonpublic Code</a></li>
</ul>
</li>
</ul>
@@ -262,9 +262,9 @@
<p>
Link to <a href="clean-code-chapter-3.html">Chapter 3</a> | Link to <a href="clean-code-chapter-5.html">Chapter 5</a>
</p>
<div id="outline-container-orgf38a65c" class="outline-2">
<h2 id="orgf38a65c">Chapter 4: Comments</h2>
<div class="outline-text-2" id="text-orgf38a65c">
<div id="outline-container-org3b3a86a" class="outline-2">
<h2 id="org3b3a86a">Chapter 4: Comments</h2>
<div class="outline-text-2" id="text-org3b3a86a">
<p>
Comments are a necessary evil—they exist because code fails to express intent clearly.
</p>
@@ -281,9 +281,9 @@ Strive to write code that explains itself; comments should be minimised.
Truth is always in the code, not in the comments.
</p>
</div>
<div id="outline-container-orgccbc8a0" class="outline-3">
<h3 id="orgccbc8a0">Comments Do Not Make Up for Bad Code</h3>
<div class="outline-text-3" id="text-orgccbc8a0">
<div id="outline-container-org563b20a" class="outline-3">
<h3 id="org563b20a">Comments Do Not Make Up for Bad Code</h3>
<div class="outline-text-3" id="text-org563b20a">
<p>
Don’t use comments to excuse messy, unclear code. Clean the code instead.
</p>
@@ -304,16 +304,16 @@ Clear, expressive code with few comments &gt; cluttered code with many comments.
</div>
</div>
</div>
<div id="outline-container-orgf7cdf31" class="outline-3">
<h3 id="orgf7cdf31">Good Comments</h3>
<div class="outline-text-3" id="text-orgf7cdf31">
<div id="outline-container-orgbb15258" class="outline-3">
<h3 id="orgbb15258">Good Comments</h3>
<div class="outline-text-3" id="text-orgbb15258">
<p>
Only write them when unavoidable. Such as in the following instances:
</p>
</div>
<div id="outline-container-org9362690" class="outline-4">
<h4 id="org9362690">Legal Comments</h4>
<div class="outline-text-4" id="text-org9362690">
<div id="outline-container-orgc8daf95" class="outline-4">
<h4 id="orgc8daf95">Legal Comments</h4>
<div class="outline-text-4" id="text-orgc8daf95">
<p>
Sometimes required for copyright/licensing.
</p>
@@ -323,9 +323,9 @@ Keep them short; refer to standard licenses rather than embedding full legal tex
</p>
</div>
</div>
<div id="outline-container-orgea06608" class="outline-4">
<h4 id="orgea06608">Informative Comments</h4>
<div class="outline-text-4" id="text-orgea06608">
<div id="outline-container-org5f86e2c" class="outline-4">
<h4 id="org5f86e2c">Informative Comments</h4>
<div class="outline-text-4" id="text-org5f86e2c">
<p>
Explain return values, formats, or patterns.
</p>
@@ -343,9 +343,9 @@ Prefer naming/structuring code to make such comments unnecessary.
</div>
</div>
</div>
<div id="outline-container-org9a8cff9" class="outline-4">
<h4 id="org9a8cff9">Explanation of Intent</h4>
<div class="outline-text-4" id="text-org9a8cff9">
<div id="outline-container-org9c9a43a" class="outline-4">
<h4 id="org9c9a43a">Explanation of Intent</h4>
<div class="outline-text-4" id="text-org9c9a43a">
<p>
Describe why a certain approach was chosen.
</p>
@@ -371,9 +371,9 @@ Helps future maintainers understand reasoning behind code.
</div>
</div>
</div>
<div id="outline-container-org756e85b" class="outline-4">
<h4 id="org756e85b">Clarification</h4>
<div class="outline-text-4" id="text-org756e85b">
<div id="outline-container-org132954b" class="outline-4">
<h4 id="org132954b">Clarification</h4>
<div class="outline-text-4" id="text-org132954b">
<p>
Translate obscure values into readable terms.
</p>
@@ -383,9 +383,9 @@ Useful when working with unchangeable APIs/libraries, but risky if incorrect.
</p>
</div>
</div>
<div id="outline-container-orge9e3aea" class="outline-4">
<h4 id="orge9e3aea">Warning of Consequences</h4>
<div class="outline-text-4" id="text-orge9e3aea">
<div id="outline-container-org2bc9356" class="outline-4">
<h4 id="org2bc9356">Warning of Consequences</h4>
<div class="outline-text-4" id="text-org2bc9356">
<p>
Alert others about performance, thread-safety, or side effects.
</p>
@@ -399,9 +399,9 @@ For example, in code you can say:
</p>
</div>
</div>
<div id="outline-container-orgda7a8c2" class="outline-4">
<h4 id="orgda7a8c2"><span class="todo TODO">TODO</span> Comments</h4>
<div class="outline-text-4" id="text-orgda7a8c2">
<div id="outline-container-org29e7534" class="outline-4">
<h4 id="org29e7534"><span class="todo TODO">TODO</span> Comments</h4>
<div class="outline-text-4" id="text-org29e7534">
<p>
Mark incomplete work or planned improvements.
</p>
@@ -411,9 +411,9 @@ Should be reviewed regularly; not an excuse for bad code.
</p>
</div>
</div>
<div id="outline-container-org7ab6062" class="outline-4">
<h4 id="org7ab6062">Amplification</h4>
<div class="outline-text-4" id="text-org7ab6062">
<div id="outline-container-org8f96c61" class="outline-4">
<h4 id="org8f96c61">Amplification</h4>
<div class="outline-text-4" id="text-org8f96c61">
<p>
Highlight the importance of seemingly small details.
</p>
@@ -423,9 +423,9 @@ Highlight the importance of seemingly small details.
</p>
</div>
</div>
<div id="outline-container-org4e714d5" class="outline-4">
<h4 id="org4e714d5">Javadocs in Public APIs</h4>
<div class="outline-text-4" id="text-org4e714d5">
<div id="outline-container-orgf0eacd6" class="outline-4">
<h4 id="orgf0eacd6">Javadocs in Public APIs</h4>
<div class="outline-text-4" id="text-orgf0eacd6">
<p>
Public APIs should have clear documentation.
</p>
@@ -436,9 +436,9 @@ Javadocs can also mislead. Keep them accurate and up-to-date.
</div>
</div>
</div>
<div id="outline-container-orgad7568e" class="outline-3">
<h3 id="orgad7568e">Bad Comments</h3>
<div class="outline-text-3" id="text-orgad7568e">
<div id="outline-container-orgeceeef2" class="outline-3">
<h3 id="orgeceeef2">Bad Comments</h3>
<div class="outline-text-3" id="text-orgeceeef2">
<ul class="org-ul">
<li>Don't place a comment just because you feel like it.</li>
<li>Remove redundant comments.</li>
@@ -448,9 +448,9 @@ Javadocs can also mislead. Keep them accurate and up-to-date.
<li>Remove noise comments.</li>
</ul>
</div>
<div id="outline-container-org4e4984e" class="outline-4">
<h4 id="org4e4984e">Don’t Use a Comment When You Can Use a Function or Variable</h4>
<div class="outline-text-4" id="text-org4e4984e">
<div id="outline-container-org8948eeb" class="outline-4">
<h4 id="org8948eeb">Don’t Use a Comment When You Can Use a Function or Variable</h4>
<div class="outline-text-4" id="text-org8948eeb">
<p>
Replace explanatory comments with expressive variable or function names.
</p>
@@ -460,9 +460,9 @@ Refactor code to remove comment redundancy.
</p>
</div>
</div>
<div id="outline-container-orgaf4e48a" class="outline-4">
<h4 id="orgaf4e48a">Position Markers</h4>
<div class="outline-text-4" id="text-orgaf4e48a">
<div id="outline-container-org9dd57c3" class="outline-4">
<h4 id="org9dd57c3">Position Markers</h4>
<div class="outline-text-4" id="text-org9dd57c3">
<p>
Avoid decorative banners like <code>// Actions ///////////////////////</code>, they add clutter.
</p>
@@ -476,9 +476,9 @@ Overuse makes them blend into background noise.
</p>
</div>
</div>
<div id="outline-container-orgb51d8f6" class="outline-4">
<h4 id="orgb51d8f6">Closing Brace Comments</h4>
<div class="outline-text-4" id="text-orgb51d8f6">
<div id="outline-container-org27ce2f1" class="outline-4">
<h4 id="org27ce2f1">Closing Brace Comments</h4>
<div class="outline-text-4" id="text-org27ce2f1">
<p>
Comments on closing braces (} // while) are unnecessary for small, well structured functions.
</p>
@@ -488,9 +488,9 @@ Prefer short, clear functions over brace markers.
</p>
</div>
</div>
<div id="outline-container-org45f7fed" class="outline-4">
<h4 id="org45f7fed">Attributions and Bylines</h4>
<div class="outline-text-4" id="text-org45f7fed">
<div id="outline-container-orgec579fa" class="outline-4">
<h4 id="orgec579fa">Attributions and Bylines</h4>
<div class="outline-text-4" id="text-orgec579fa">
<p>
Don’t add personal tags like <code>/* Added by Rick */</code>, use version control for authorship history.
</p>
@@ -500,9 +500,9 @@ Such comments become outdated and irrelevant over time.
</p>
</div>
</div>
<div id="outline-container-orgd72549e" class="outline-4">
<h4 id="orgd72549e">Commented Out Code</h4>
<div class="outline-text-4" id="text-orgd72549e">
<div id="outline-container-org5ae47be" class="outline-4">
<h4 id="org5ae47be">Commented Out Code</h4>
<div class="outline-text-4" id="text-org5ae47be">
<p>
Never keep old code commented out; delete it and rely on version control history.
</p>
@@ -521,9 +521,9 @@ Commented-out code adds clutter and confuses future maintainers.
</div>
</div>
</div>
<div id="outline-container-orga4d406b" class="outline-4">
<h4 id="orga4d406b">HTML Comments</h4>
<div class="outline-text-4" id="text-orga4d406b">
<div id="outline-container-orgfe581e3" class="outline-4">
<h4 id="orgfe581e3">HTML Comments</h4>
<div class="outline-text-4" id="text-orgfe581e3">
<p>
Avoid HTML markup inside code comments, it makes them harder to read in the editor.
</p>
@@ -533,9 +533,9 @@ Let documentation tools (like Javadoc) handle formatting.
</p>
</div>
</div>
<div id="outline-container-org191c38a" class="outline-4">
<h4 id="org191c38a">Nonlocal Information</h4>
<div class="outline-text-4" id="text-org191c38a">
<div id="outline-container-org458bb98" class="outline-4">
<h4 id="org458bb98">Nonlocal Information</h4>
<div class="outline-text-4" id="text-org458bb98">
<p>
Comments should describe nearby code only, not unrelated parts of the system.
</p>
@@ -545,9 +545,9 @@ Avoid embedding global/system details that the function can’t control.
</p>
</div>
</div>
<div id="outline-container-org66a46c7" class="outline-4">
<h4 id="org66a46c7">Too Much Information</h4>
<div class="outline-text-4" id="text-org66a46c7">
<div id="outline-container-org6d8a526" class="outline-4">
<h4 id="org6d8a526">Too Much Information</h4>
<div class="outline-text-4" id="text-org6d8a526">
<p>
Avoid long, unnecessary historical or technical explanations.
</p>
@@ -557,9 +557,9 @@ Keep only relevant context (e.g., “RFC 2045” reference is fine, not the full
</p>
</div>
</div>
<div id="outline-container-org1de4858" class="outline-4">
<h4 id="org1de4858">Inobvious Connection</h4>
<div class="outline-text-4" id="text-org1de4858">
<div id="outline-container-org99e4520" class="outline-4">
<h4 id="org99e4520">Inobvious Connection</h4>
<div class="outline-text-4" id="text-org99e4520">
<p>
Ensure the relationship between comment and code is clear.
</p>
@@ -577,9 +577,9 @@ Don’t make readers guess what part of the code the comment refers to.
</div>
</div>
</div>
<div id="outline-container-orgec05bc1" class="outline-4">
<h4 id="orgec05bc1">Function Headers</h4>
<div class="outline-text-4" id="text-orgec05bc1">
<div id="outline-container-org856f330" class="outline-4">
<h4 id="org856f330">Function Headers</h4>
<div class="outline-text-4" id="text-org856f330">
<p>
Short, single purpose functions with good names don’t need header comments.
</p>
@@ -589,9 +589,9 @@ Let the function name explain the purpose.
</p>
</div>
</div>
<div id="outline-container-org9f353fd" class="outline-4">
<h4 id="org9f353fd">Javadocs in Nonpublic Code</h4>
<div class="outline-text-4" id="text-org9f353fd">
<div id="outline-container-org080d921" class="outline-4">
<h4 id="org080d921">Javadocs in Nonpublic Code</h4>
<div class="outline-text-4" id="text-org080d921">
<p>
Javadocs are useful for public APIs, but excessive formality in internal code is just noise.
</p>