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

Auto-publish on Thu 28 Aug 17:41:03 BST 2025

Browse Source
This commit is contained in:
Zaine Arch
2025-08-28 17:41:03 +01:00
parent 04f8538754
commit ea2fe05037
38 changed files with 787 additions and 492 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:03 -->
<!-- 2025-08-28 Thu 17:40 -->
<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="#org654cde4">Chapter 4: Comments</a>
<li><a href="#org6a1be50">Chapter 4: Comments</a>
<ul>
<li><a href="#orga48d099">Comments Do Not Make Up for Bad Code</a></li>
<li><a href="#org8a9af22">Good Comments</a>
<li><a href="#org38a85de">Comments Do Not Make Up for Bad Code</a></li>
<li><a href="#org3d21f6c">Good Comments</a>
<ul>
<li><a href="#orga00e43a">Legal Comments</a></li>
<li><a href="#org5d052d2">Informative Comments</a></li>
<li><a href="#orgc07d869">Explanation of Intent</a></li>
<li><a href="#orgeac0874">Clarification</a></li>
<li><a href="#org925a6b4">Warning of Consequences</a></li>
<li><a href="#org3c48674"><span class="todo TODO">TODO</span> Comments</a></li>
<li><a href="#org40776a2">Amplification</a></li>
<li><a href="#orga01f4c8">Javadocs in Public APIs</a></li>
<li><a href="#org60faf90">Legal Comments</a></li>
<li><a href="#org4c03b28">Informative Comments</a></li>
<li><a href="#org89d84dd">Explanation of Intent</a></li>
<li><a href="#org147392d">Clarification</a></li>
<li><a href="#orgcbd8f61">Warning of Consequences</a></li>
<li><a href="#org10dc31f"><span class="todo TODO">TODO</span> Comments</a></li>
<li><a href="#orge3c8120">Amplification</a></li>
<li><a href="#org1c2990b">Javadocs in Public APIs</a></li>
</ul>
</li>
<li><a href="#orgdf9d0a0">Bad Comments</a>
<li><a href="#org1383acc">Bad Comments</a>
<ul>
<li><a href="#org513ee74">Don’t Use a Comment When You Can Use a Function or Variable</a></li>
<li><a href="#org47d711f">Position Markers</a></li>
<li><a href="#org166362e">Closing Brace Comments</a></li>
<li><a href="#orga7d0949">Attributions and Bylines</a></li>
<li><a href="#org087890b">Commented Out Code</a></li>
<li><a href="#org2707e8f">HTML Comments</a></li>
<li><a href="#orgd3ef1af">Nonlocal Information</a></li>
<li><a href="#org6859e2c">Too Much Information</a></li>
<li><a href="#orgd7d19c8">Inobvious Connection</a></li>
<li><a href="#org24f323a">Function Headers</a></li>
<li><a href="#orgd626f64">Javadocs in Nonpublic Code</a></li>
<li><a href="#org70b00fd">Don’t Use a Comment When You Can Use a Function or Variable</a></li>
<li><a href="#org6dc1eb9">Position Markers</a></li>
<li><a href="#org96c1712">Closing Brace Comments</a></li>
<li><a href="#org08bd78d">Attributions and Bylines</a></li>
<li><a href="#orgef8c07d">Commented Out Code</a></li>
<li><a href="#org1f7eb78">HTML Comments</a></li>
<li><a href="#orgda710fa">Nonlocal Information</a></li>
<li><a href="#org758b635">Too Much Information</a></li>
<li><a href="#org015cffe">Inobvious Connection</a></li>
<li><a href="#orga50fdc5">Function Headers</a></li>
<li><a href="#orgeb64351">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-org654cde4" class="outline-2">
<h2 id="org654cde4">Chapter 4: Comments</h2>
<div class="outline-text-2" id="text-org654cde4">
<div id="outline-container-org6a1be50" class="outline-2">
<h2 id="org6a1be50">Chapter 4: Comments</h2>
<div class="outline-text-2" id="text-org6a1be50">
<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-orga48d099" class="outline-3">
<h3 id="orga48d099">Comments Do Not Make Up for Bad Code</h3>
<div class="outline-text-3" id="text-orga48d099">
<div id="outline-container-org38a85de" class="outline-3">
<h3 id="org38a85de">Comments Do Not Make Up for Bad Code</h3>
<div class="outline-text-3" id="text-org38a85de">
<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-org8a9af22" class="outline-3">
<h3 id="org8a9af22">Good Comments</h3>
<div class="outline-text-3" id="text-org8a9af22">
<div id="outline-container-org3d21f6c" class="outline-3">
<h3 id="org3d21f6c">Good Comments</h3>
<div class="outline-text-3" id="text-org3d21f6c">
<p>
Only write them when unavoidable. Such as in the following instances:
</p>
</div>
<div id="outline-container-orga00e43a" class="outline-4">
<h4 id="orga00e43a">Legal Comments</h4>
<div class="outline-text-4" id="text-orga00e43a">
<div id="outline-container-org60faf90" class="outline-4">
<h4 id="org60faf90">Legal Comments</h4>
<div class="outline-text-4" id="text-org60faf90">
<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-org5d052d2" class="outline-4">
<h4 id="org5d052d2">Informative Comments</h4>
<div class="outline-text-4" id="text-org5d052d2">
<div id="outline-container-org4c03b28" class="outline-4">
<h4 id="org4c03b28">Informative Comments</h4>
<div class="outline-text-4" id="text-org4c03b28">
<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-orgc07d869" class="outline-4">
<h4 id="orgc07d869">Explanation of Intent</h4>
<div class="outline-text-4" id="text-orgc07d869">
<div id="outline-container-org89d84dd" class="outline-4">
<h4 id="org89d84dd">Explanation of Intent</h4>
<div class="outline-text-4" id="text-org89d84dd">
<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-orgeac0874" class="outline-4">
<h4 id="orgeac0874">Clarification</h4>
<div class="outline-text-4" id="text-orgeac0874">
<div id="outline-container-org147392d" class="outline-4">
<h4 id="org147392d">Clarification</h4>
<div class="outline-text-4" id="text-org147392d">
<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-org925a6b4" class="outline-4">
<h4 id="org925a6b4">Warning of Consequences</h4>
<div class="outline-text-4" id="text-org925a6b4">
<div id="outline-container-orgcbd8f61" class="outline-4">
<h4 id="orgcbd8f61">Warning of Consequences</h4>
<div class="outline-text-4" id="text-orgcbd8f61">
<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-org3c48674" class="outline-4">
<h4 id="org3c48674"><span class="todo TODO">TODO</span> Comments</h4>
<div class="outline-text-4" id="text-org3c48674">
<div id="outline-container-org10dc31f" class="outline-4">
<h4 id="org10dc31f"><span class="todo TODO">TODO</span> Comments</h4>
<div class="outline-text-4" id="text-org10dc31f">
<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-org40776a2" class="outline-4">
<h4 id="org40776a2">Amplification</h4>
<div class="outline-text-4" id="text-org40776a2">
<div id="outline-container-orge3c8120" class="outline-4">
<h4 id="orge3c8120">Amplification</h4>
<div class="outline-text-4" id="text-orge3c8120">
<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-orga01f4c8" class="outline-4">
<h4 id="orga01f4c8">Javadocs in Public APIs</h4>
<div class="outline-text-4" id="text-orga01f4c8">
<div id="outline-container-org1c2990b" class="outline-4">
<h4 id="org1c2990b">Javadocs in Public APIs</h4>
<div class="outline-text-4" id="text-org1c2990b">
<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-orgdf9d0a0" class="outline-3">
<h3 id="orgdf9d0a0">Bad Comments</h3>
<div class="outline-text-3" id="text-orgdf9d0a0">
<div id="outline-container-org1383acc" class="outline-3">
<h3 id="org1383acc">Bad Comments</h3>
<div class="outline-text-3" id="text-org1383acc">
<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-org513ee74" class="outline-4">
<h4 id="org513ee74">Don’t Use a Comment When You Can Use a Function or Variable</h4>
<div class="outline-text-4" id="text-org513ee74">
<div id="outline-container-org70b00fd" class="outline-4">
<h4 id="org70b00fd">Don’t Use a Comment When You Can Use a Function or Variable</h4>
<div class="outline-text-4" id="text-org70b00fd">
<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-org47d711f" class="outline-4">
<h4 id="org47d711f">Position Markers</h4>
<div class="outline-text-4" id="text-org47d711f">
<div id="outline-container-org6dc1eb9" class="outline-4">
<h4 id="org6dc1eb9">Position Markers</h4>
<div class="outline-text-4" id="text-org6dc1eb9">
<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-org166362e" class="outline-4">
<h4 id="org166362e">Closing Brace Comments</h4>
<div class="outline-text-4" id="text-org166362e">
<div id="outline-container-org96c1712" class="outline-4">
<h4 id="org96c1712">Closing Brace Comments</h4>
<div class="outline-text-4" id="text-org96c1712">
<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-orga7d0949" class="outline-4">
<h4 id="orga7d0949">Attributions and Bylines</h4>
<div class="outline-text-4" id="text-orga7d0949">
<div id="outline-container-org08bd78d" class="outline-4">
<h4 id="org08bd78d">Attributions and Bylines</h4>
<div class="outline-text-4" id="text-org08bd78d">
<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-org087890b" class="outline-4">
<h4 id="org087890b">Commented Out Code</h4>
<div class="outline-text-4" id="text-org087890b">
<div id="outline-container-orgef8c07d" class="outline-4">
<h4 id="orgef8c07d">Commented Out Code</h4>
<div class="outline-text-4" id="text-orgef8c07d">
<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-org2707e8f" class="outline-4">
<h4 id="org2707e8f">HTML Comments</h4>
<div class="outline-text-4" id="text-org2707e8f">
<div id="outline-container-org1f7eb78" class="outline-4">
<h4 id="org1f7eb78">HTML Comments</h4>
<div class="outline-text-4" id="text-org1f7eb78">
<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-orgd3ef1af" class="outline-4">
<h4 id="orgd3ef1af">Nonlocal Information</h4>
<div class="outline-text-4" id="text-orgd3ef1af">
<div id="outline-container-orgda710fa" class="outline-4">
<h4 id="orgda710fa">Nonlocal Information</h4>
<div class="outline-text-4" id="text-orgda710fa">
<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-org6859e2c" class="outline-4">
<h4 id="org6859e2c">Too Much Information</h4>
<div class="outline-text-4" id="text-org6859e2c">
<div id="outline-container-org758b635" class="outline-4">
<h4 id="org758b635">Too Much Information</h4>
<div class="outline-text-4" id="text-org758b635">
<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-orgd7d19c8" class="outline-4">
<h4 id="orgd7d19c8">Inobvious Connection</h4>
<div class="outline-text-4" id="text-orgd7d19c8">
<div id="outline-container-org015cffe" class="outline-4">
<h4 id="org015cffe">Inobvious Connection</h4>
<div class="outline-text-4" id="text-org015cffe">
<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-org24f323a" class="outline-4">
<h4 id="org24f323a">Function Headers</h4>
<div class="outline-text-4" id="text-org24f323a">
<div id="outline-container-orga50fdc5" class="outline-4">
<h4 id="orga50fdc5">Function Headers</h4>
<div class="outline-text-4" id="text-orga50fdc5">
<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-orgd626f64" class="outline-4">
<h4 id="orgd626f64">Javadocs in Nonpublic Code</h4>
<div class="outline-text-4" id="text-orgd626f64">
<div id="outline-container-orgeb64351" class="outline-4">
<h4 id="orgeb64351">Javadocs in Nonpublic Code</h4>
<div class="outline-text-4" id="text-orgeb64351">
<p>
Javadocs are useful for public APIs, but excessive formality in internal code is just noise.
</p>