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:04:32 BST 2025

Browse Source
This commit is contained in:
Zaine Arch
2025-08-28 17:04:32 +01:00
parent f7b8c4c276
commit 04f8538754
36 changed files with 1534 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
output/posts/clean-code/clean-code-chapter-1.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-27 Wed 22:32 -->
<!-- 2025-08-28 Thu 17:03 -->
<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 1 Notes</title>
@@ -224,16 +224,16 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#org68cf69c">Chapter 1: Clean Code</a></li>
<li><a href="#org64a0552">Chapter 1: Clean Code</a></li>
</ul>
</div>
</div>
<p>
Link to <a href="clean-code-chapter-2.html">Chapter 2</a>
</p>
<div id="outline-container-org68cf69c" class="outline-2">
<h2 id="org68cf69c">Chapter 1: Clean Code</h2>
<div class="outline-text-2" id="text-org68cf69c">
<div id="outline-container-org64a0552" class="outline-2">
<h2 id="org64a0552">Chapter 1: Clean Code</h2>
<div class="outline-text-2" id="text-org64a0552">
<p>
Referenced Items:
</p>

127
output/posts/clean-code/clean-code-chapter-2.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-27 Wed 22:32 -->
<!-- 2025-08-28 Thu 17:03 -->
<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 2 Notes</title>
@@ -214,7 +214,7 @@
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-12 Tue 18:29</div>
<div id="updated">Updated: 2025-08-28 Thu 16:52</div>
</div>
<div id="content" class="content">
<h1 class="title">Clean Code: Chapter 2 Notes</h1>
@@ -224,38 +224,37 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#org3895e8e">Chapter 2: Meaningful Names</a>
<li><a href="#org80b6e4c">Chapter 2: Meaningful Names</a>
<ul>
<li><a href="#org5dea215">Use intention revealing names:</a></li>
<li><a href="#orgccfede2">Avoid disinformation</a></li>
<li><a href="#orgcd10be2">Make Meaningful Distinctions</a></li>
<li><a href="#org376cc29">Use Pronouncable Names</a></li>
<li><a href="#org1cd2df5">Use Searchable Names</a></li>
<li><a href="#org9ef4c1d">Avoid Encodings</a></li>
<li><a href="#org069b38f">Avoid Mental Mappings</a></li>
<li><a href="#orgb99f057">Class Names</a></li>
<li><a href="#orga0217c7">Method Names</a></li>
<li><a href="#org8f0b520">Don't be cute/Don't use puns</a></li>
<li><a href="#orgad1888f">Pick one word per concept</a></li>
<li><a href="#org8c1296e">Solution Domain Names and Problem Domain Names</a></li>
<li><a href="#orge46f850">Add Meaningful Context</a></li>
<li><a href="#orgf493568">Don't add gratuitous context</a></li>
<li><a href="#orgd2efe25">Use intention revealing names:</a></li>
<li><a href="#org3cbde76">Avoid disinformation</a></li>
<li><a href="#org61138b3">Make Meaningful Distinctions</a></li>
<li><a href="#orgd9a3209">Use Pronouncable Names</a></li>
<li><a href="#org1654166">Use Searchable Names</a></li>
<li><a href="#org63b79b1">Avoid Encodings</a></li>
<li><a href="#org44388c4">Avoid Mental Mappings</a></li>
<li><a href="#orgcf20903">Class Names</a></li>
<li><a href="#org6e3f9c3">Method Names</a></li>
<li><a href="#orgd0258e8">Don't be cute/Don't use puns</a></li>
<li><a href="#org8a49053">Pick one word per concept</a></li>
<li><a href="#org17ad381">Solution Domain Names and Problem Domain Names</a></li>
<li><a href="#orgbf4a7fc">Add Meaningful Context</a></li>
<li><a href="#org1ebc857">Don't add gratuitous context</a></li>
</ul>
</li>
</ul>
</div>
</div>
<p>
Link to <a href="clean-code-chapter-1.html">Chapter 1</a>
Link to <a href="clean-code-chapter-3.html">Chapter 3</a>
Link to <a href="clean-code-chapter-1.html">Chapter 1</a> | Link to <a href="clean-code-chapter-3.html">Chapter 3</a>
</p>
<div id="outline-container-org3895e8e" class="outline-2">
<h2 id="org3895e8e">Chapter 2: Meaningful Names</h2>
<div class="outline-text-2" id="text-org3895e8e">
<div id="outline-container-org80b6e4c" class="outline-2">
<h2 id="org80b6e4c">Chapter 2: Meaningful Names</h2>
<div class="outline-text-2" id="text-org80b6e4c">
</div>
<div id="outline-container-org5dea215" class="outline-3">
<h3 id="org5dea215">Use intention revealing names:</h3>
<div class="outline-text-3" id="text-org5dea215">
<div id="outline-container-orgd2efe25" class="outline-3">
<h3 id="orgd2efe25">Use intention revealing names:</h3>
<div class="outline-text-3" id="text-orgd2efe25">
<p>
Names should reveal intent, there is no revelation in naming an integer <code>d</code>, intending it stands for days. Instead, you should use the following names:
</p>
@@ -268,17 +267,17 @@ Names should reveal intent, there is no revelation in naming an integer <code>d<
</div>
</div>
</div>
<div id="outline-container-orgccfede2" class="outline-3">
<h3 id="orgccfede2">Avoid disinformation</h3>
<div class="outline-text-3" id="text-orgccfede2">
<div id="outline-container-org3cbde76" class="outline-3">
<h3 id="org3cbde76">Avoid disinformation</h3>
<div class="outline-text-3" id="text-org3cbde76">
<p>
Don't postfix the word 'list' to the name 'accounts' unless it's actually a list. This is because the reader will <i>assume</i> the data type of accountsList is indeed a list, instead choose a name like <code>accountsGroup</code>.
</p>
</div>
</div>
<div id="outline-container-orgcd10be2" class="outline-3">
<h3 id="orgcd10be2">Make Meaningful Distinctions</h3>
<div class="outline-text-3" id="text-orgcd10be2">
<div id="outline-container-org61138b3" class="outline-3">
<h3 id="org61138b3">Make Meaningful Distinctions</h3>
<div class="outline-text-3" id="text-org61138b3">
<p>
While it is possible to name by being disinformative, it is also possible to name being non informative. Consider:
</p>
@@ -303,18 +302,18 @@ Furthermore, noise words are redundant. We should never use the word <code>varia
</p>
</div>
</div>
<div id="outline-container-org376cc29" class="outline-3">
<h3 id="org376cc29">Use Pronouncable Names</h3>
<div class="outline-text-3" id="text-org376cc29">
<div id="outline-container-orgd9a3209" class="outline-3">
<h3 id="orgd9a3209">Use Pronouncable Names</h3>
<div class="outline-text-3" id="text-orgd9a3209">
<p>
This is quite straightforward. Do not use a name like <code>genymdhms</code> to refer to generation date, year, month, day, hour, minute,
and second. Instead use <code>generationTimeStamp</code>.
</p>
</div>
</div>
<div id="outline-container-org1cd2df5" class="outline-3">
<h3 id="org1cd2df5">Use Searchable Names</h3>
<div class="outline-text-3" id="text-org1cd2df5">
<div id="outline-container-org1654166" class="outline-3">
<h3 id="org1654166">Use Searchable Names</h3>
<div class="outline-text-3" id="text-org1654166">
<p>
In modern IDE's, it is still quite difficult to search for single-lettered variables. The writer states a personal preference of using single-letter names only as local variables and inside short methods. The following principle is given:
</p>
@@ -324,42 +323,42 @@ In modern IDE's, it is still quite difficult to search for single-lettered varia
</p>
</div>
</div>
<div id="outline-container-org9ef4c1d" class="outline-3">
<h3 id="org9ef4c1d">Avoid Encodings</h3>
<div class="outline-text-3" id="text-org9ef4c1d">
<div id="outline-container-org63b79b1" class="outline-3">
<h3 id="org63b79b1">Avoid Encodings</h3>
<div class="outline-text-3" id="text-org63b79b1">
<p>
Don't prefix variables with letters like m_ as was done in the past. Do not type encode as well, an example of this is: <code>PhoneNumber phoneString;</code> we can see the reader being misled into thinking the phone number is a String.
</p>
</div>
</div>
<div id="outline-container-org069b38f" class="outline-3">
<h3 id="org069b38f">Avoid Mental Mappings</h3>
<div class="outline-text-3" id="text-org069b38f">
<div id="outline-container-org44388c4" class="outline-3">
<h3 id="org44388c4">Avoid Mental Mappings</h3>
<div class="outline-text-3" id="text-org44388c4">
<p>
Clarity is king, don't use a name for a variable that only you know what it stands for. For example: using the letter r as the lower-cased version of the url with the host and scheme
removed. That's being smart, not professional.
</p>
</div>
</div>
<div id="outline-container-orgb99f057" class="outline-3">
<h3 id="orgb99f057">Class Names</h3>
<div class="outline-text-3" id="text-orgb99f057">
<div id="outline-container-orgcf20903" class="outline-3">
<h3 id="orgcf20903">Class Names</h3>
<div class="outline-text-3" id="text-orgcf20903">
<p>
<div class="epigraph"><blockquote>Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb</blockquote></div>
</p>
</div>
</div>
<div id="outline-container-orga0217c7" class="outline-3">
<h3 id="orga0217c7">Method Names</h3>
<div class="outline-text-3" id="text-orga0217c7">
<div id="outline-container-org6e3f9c3" class="outline-3">
<h3 id="org6e3f9c3">Method Names</h3>
<div class="outline-text-3" id="text-org6e3f9c3">
<p>
Methods should have verb or verb phrase names.
</p>
</div>
</div>
<div id="outline-container-org8f0b520" class="outline-3">
<h3 id="org8f0b520">Don't be cute/Don't use puns</h3>
<div class="outline-text-3" id="text-org8f0b520">
<div id="outline-container-orgd0258e8" class="outline-3">
<h3 id="orgd0258e8">Don't be cute/Don't use puns</h3>
<div class="outline-text-3" id="text-orgd0258e8">
<p>
Do not use names that are only understandable to people whom you share jokes etc with. Furthermore, do not use colloquialism and slang in names.
</p>
@@ -369,17 +368,17 @@ Do not use names that are only understandable to people whom you share jokes etc
</ul>
</div>
</div>
<div id="outline-container-orgad1888f" class="outline-3">
<h3 id="orgad1888f">Pick one word per concept</h3>
<div class="outline-text-3" id="text-orgad1888f">
<div id="outline-container-org8a49053" class="outline-3">
<h3 id="org8a49053">Pick one word per concept</h3>
<div class="outline-text-3" id="text-org8a49053">
<p>
If you have multiple choices for naming a concept, use one and stick with it. For instance if your options are fetch, get and retrieve, use one and stick with it throughout.
</p>
</div>
</div>
<div id="outline-container-org8c1296e" class="outline-3">
<h3 id="org8c1296e">Solution Domain Names and Problem Domain Names</h3>
<div class="outline-text-3" id="text-org8c1296e">
<div id="outline-container-org17ad381" class="outline-3">
<h3 id="org17ad381">Solution Domain Names and Problem Domain Names</h3>
<div class="outline-text-3" id="text-org17ad381">
<p>
Where possible use solution domain names, as the people that are going to be reading the code are programmers. Therefore, do not shy away from using CS terms, algorithm names, math names and so forth.
</p>
@@ -389,17 +388,17 @@ However when it is not possible to use solution domain names (in other words, wh
</p>
</div>
</div>
<div id="outline-container-orge46f850" class="outline-3">
<h3 id="orge46f850">Add Meaningful Context</h3>
<div class="outline-text-3" id="text-orge46f850">
<div id="outline-container-orgbf4a7fc" class="outline-3">
<h3 id="orgbf4a7fc">Add Meaningful Context</h3>
<div class="outline-text-3" id="text-orgbf4a7fc">
<p>
Enclose names with well-named classes, functions, or namespaces. When all else fails, then prefix with something that provides more context.
</p>
</div>
</div>
<div id="outline-container-orgf493568" class="outline-3">
<h3 id="orgf493568">Don't add gratuitous context</h3>
<div class="outline-text-3" id="text-orgf493568">
<div id="outline-container-org1ebc857" class="outline-3">
<h3 id="org1ebc857">Don't add gratuitous context</h3>
<div class="outline-text-3" id="text-org1ebc857">
<p>
Shorter names are better than longer ones, generally. This is so long as the context and intent is clear. Don't add redundant or irrelevant additions to the name in the for the sake of 'context'.
</p>

70
output/posts/clean-code/clean-code-chapter-3.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-27 Wed 22:32 -->
<!-- 2025-08-28 Thu 17:03 -->
<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 3 Notes</title>
@@ -214,7 +214,7 @@
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-12 Tue 18:30</div>
<div id="updated">Updated: 2025-08-28 Thu 16:52</div>
</div>
<div id="content" class="content">
<h1 class="title">Clean Code: Chapter 3 Notes</h1>
@@ -224,30 +224,30 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#org8f14a94">Chapter 3: Functions</a>
<li><a href="#org9ddaa82">Chapter 3: Functions</a>
<ul>
<li><a href="#org307e775">Functions should be small</a></li>
<li><a href="#org494d49b">Do One Thing &amp; One Level of Abstraction</a></li>
<li><a href="#org388f480">Switch Statements</a></li>
<li><a href="#orgef9c0c6">Use Descriptive Names</a></li>
<li><a href="#org659f406">Function Arguments</a></li>
<li><a href="#org59cfd1e">Have No Side Effects</a></li>
<li><a href="#orga4a5d03">Error Handling</a></li>
<li><a href="#orgd79ec8c">Functions should be small</a></li>
<li><a href="#org1f5cd51">Do One Thing &amp; One Level of Abstraction</a></li>
<li><a href="#org1008156">Switch Statements</a></li>
<li><a href="#orgf5e89a5">Use Descriptive Names</a></li>
<li><a href="#org811abac">Function Arguments</a></li>
<li><a href="#org36f6cc1">Have No Side Effects</a></li>
<li><a href="#org83f5e96">Error Handling</a></li>
</ul>
</li>
</ul>
</div>
</div>
<p>
Link to <a href="clean-code-chapter-2.html">Chapter 2</a>
Link to <a href="clean-code-chapter-2.html">Chapter 2</a> | Link to <a href="clean-code-chapter-4.html">Chapter 4</a>
</p>
<div id="outline-container-org8f14a94" class="outline-2">
<h2 id="org8f14a94">Chapter 3: Functions</h2>
<div class="outline-text-2" id="text-org8f14a94">
<div id="outline-container-org9ddaa82" class="outline-2">
<h2 id="org9ddaa82">Chapter 3: Functions</h2>
<div class="outline-text-2" id="text-org9ddaa82">
</div>
<div id="outline-container-org307e775" class="outline-3">
<h3 id="org307e775">Functions should be small</h3>
<div class="outline-text-3" id="text-org307e775">
<div id="outline-container-orgd79ec8c" class="outline-3">
<h3 id="orgd79ec8c">Functions should be small</h3>
<div class="outline-text-3" id="text-orgd79ec8c">
<p>
Functions should be extremely short—ideally just a few lines, so they remain easy to understand and maintain.
</p>
@@ -269,9 +269,9 @@ Large functions hide complexity and mix abstraction levels, making errors and du
</p>
</div>
</div>
<div id="outline-container-org494d49b" class="outline-3">
<h3 id="org494d49b">Do One Thing &amp; One Level of Abstraction</h3>
<div class="outline-text-3" id="text-org494d49b">
<div id="outline-container-org1f5cd51" class="outline-3">
<h3 id="org1f5cd51">Do One Thing &amp; One Level of Abstraction</h3>
<div class="outline-text-3" id="text-org1f5cd51">
<p>
A function should do exactly one conceptual task, and all its statements should exist at the same abstraction level.
</p>
@@ -293,9 +293,9 @@ Functions that “do one thing” cannot be logically split into sections such a
</p>
</div>
</div>
<div id="outline-container-org388f480" class="outline-3">
<h3 id="org388f480">Switch Statements</h3>
<div class="outline-text-3" id="text-org388f480">
<div id="outline-container-org1008156" class="outline-3">
<h3 id="org1008156">Switch Statements</h3>
<div class="outline-text-3" id="text-org1008156">
<p>
Switch statements naturally violate “do one thing” by handling multiple cases; they also grow in size over time.
</p>
@@ -350,9 +350,9 @@ Example:
</div>
</div>
</div>
<div id="outline-container-orgef9c0c6" class="outline-3">
<h3 id="orgef9c0c6">Use Descriptive Names</h3>
<div class="outline-text-3" id="text-orgef9c0c6">
<div id="outline-container-orgf5e89a5" class="outline-3">
<h3 id="orgf5e89a5">Use Descriptive Names</h3>
<div class="outline-text-3" id="text-orgf5e89a5">
<p>
A function’s name should clearly state its purpose. Long, descriptive names beat short, cryptic ones.
</p>
@@ -374,9 +374,9 @@ IDE refactoring tools make renaming safe, encouraging experimentation.
</p>
</div>
</div>
<div id="outline-container-org659f406" class="outline-3">
<h3 id="org659f406">Function Arguments</h3>
<div class="outline-text-3" id="text-org659f406">
<div id="outline-container-org811abac" class="outline-3">
<h3 id="org811abac">Function Arguments</h3>
<div class="outline-text-3" id="text-org811abac">
<p>
<div class="epigraph"><blockquote>The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.</blockquote></div>
</p>
@@ -402,9 +402,9 @@ Match function/argument names in verb–noun or keyword style (e.g., <code>write
</p>
</div>
</div>
<div id="outline-container-org59cfd1e" class="outline-3">
<h3 id="org59cfd1e">Have No Side Effects</h3>
<div class="outline-text-3" id="text-org59cfd1e">
<div id="outline-container-org36f6cc1" class="outline-3">
<h3 id="org36f6cc1">Have No Side Effects</h3>
<div class="outline-text-3" id="text-org36f6cc1">
<p>
A function should do only what its name promises. Hidden state changes are misleading and dangerous.
</p>
@@ -426,9 +426,9 @@ Functions that modify state and return information often cause confusion and sho
</p>
</div>
</div>
<div id="outline-container-orga4a5d03" class="outline-3">
<h3 id="orga4a5d03">Error Handling</h3>
<div class="outline-text-3" id="text-orga4a5d03">
<div id="outline-container-org83f5e96" class="outline-3">
<h3 id="org83f5e96">Error Handling</h3>
<div class="outline-text-3" id="text-org83f5e96">
<p>
Error handling is a single responsibility—separate it from normal logic to keep both paths clear.
</p>

618
output/posts/clean-code/clean-code-chapter-4.html Normal file
View File

@@ -0,0 +1,618 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"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 -->
<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>
<meta name="generator" content="Org Mode" />
<style type="text/css">
#content { max-width: 60em; margin: auto; }
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #e6e6e6;
border-radius: 3px;
background-color: #f2f2f2;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: auto;
}
pre.src:before {
display: none;
position: absolute;
top: -8px;
right: 12px;
padding: 3px;
color: #555;
background-color: #f2f2f299;
}
pre.src:hover:before { display: inline; margin-top: 14px;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-authinfo::before { content: 'Authinfo'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { }
</style>
<link rel="stylesheet" href="/assets/styles/style.css" />
<link rel="stylesheet" href="/assets/styles/bigger-picture.min.css" />
<script src="/assets/scripts/script.js" defer></script>
<script src="/assets/scripts/bigger-picture.min.js" defer></script>
<script src="/assets/scripts/svg-pan-zoom.min.js" defer></script>
<script src="/assets/scripts/gallery-init.js" defer></script>
</head>
<body>
<div id="preamble" class="status">
<div class="banner-header">
<a href="/"> <img src="/assets/images/gr.png" alt="Site Logo" class="banner-logo" /> </a>
<nav>
<a href="/">Home | </a>
<a href="/posts/posts-list.html">Posts | </a>
<a href="/blogs/blogs-list.html">Blogs | </a>
<a href="/contact.html">Contact</a>
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-28 Thu 16:52</div>
</div>
<div id="content" class="content">
<h1 class="title">Clean Code: Chapter 4 Notes</h1>
<div class="filetags"><a href="/categories.html"> <span class="post-tag">books</span> </a> <a href="/categories.html"> <span class="post-tag">notes</span> </a></div>
<div id="table-of-contents" role="doc-toc">
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#org654cde4">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>
<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>
</ul>
</li>
<li><a href="#orgdf9d0a0">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>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<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">
<p>
Comments are a necessary evil—they exist because code fails to express intent clearly.
</p>
<p>
Outdated comments are dangerous; they can mislead more than help.
</p>
<p>
Strive to write code that explains itself; comments should be minimised.
</p>
<p>
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">
<p>
Don’t use comments to excuse messy, unclear code. Clean the code instead.
</p>
<p>
Clear, expressive code with few comments &gt; cluttered code with many comments.
</p>
<div class="org-src-container">
<pre class="src src-java">
<span class="org-comment-delimiter">// </span><span class="org-comment">Check to see if the employee is eligible for full benefits
</span><span class="org-keyword">if</span> ((employee.flags &amp; HOURLY_FLAG) &amp;&amp; (employee.age &gt; 65))
<span class="org-comment-delimiter">// </span><span class="org-comment">Better:
</span><span class="org-keyword">if</span> (employee.isEligibleForFullBenefits())
</pre>
</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">
<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">
<p>
Sometimes required for copyright/licensing.
</p>
<p>
Keep them short; refer to standard licenses rather than embedding full legal text.
</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">
<p>
Explain return values, formats, or patterns.
</p>
<p>
Prefer naming/structuring code to make such comments unnecessary.
</p>
<div class="org-src-container">
<pre class="src src-java">
<span class="org-comment-delimiter">// </span><span class="org-comment">format matched kk:mm:ss EEE, MMM dd, yyyy
</span><span class="org-type">Pattern</span> <span class="org-variable-name">timeMatcher</span> = Pattern.compile(<span class="org-string">"\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*"</span>);
</pre>
</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">
<p>
Describe why a certain approach was chosen.
</p>
<p>
Helps future maintainers understand reasoning behind code.
</p>
<div class="org-src-container">
<pre class="src src-java">
<span class="org-keyword">public</span> <span class="org-type">int</span> <span class="org-function-name">compareTo</span>(<span class="org-type">Object</span> <span class="org-variable-name">o</span>)
{
<span class="org-keyword">if</span>(o <span class="org-keyword">instanceof</span> WikiPagePath)
{ <span class="org-type">WikiPagePath</span> <span class="org-variable-name">p</span> = (<span class="org-type">WikiPagePath</span>) o;
<span class="org-type">String</span> <span class="org-variable-name">compressedName</span> = StringUtil.join(names, <span class="org-string">""</span>);
<span class="org-type">String</span> <span class="org-variable-name">compressedArgumentName</span> = StringUtil.join(p.names, <span class="org-string">""</span>);
<span class="org-keyword">return</span> compressedName.compareTo(compressedArgumentName);
}
<span class="org-keyword">return</span> 1; <span class="org-comment-delimiter">// </span><span class="org-comment">we are greater because we are the right type.
</span>}
</pre>
</div>
</div>
</div>
<div id="outline-container-orgeac0874" class="outline-4">
<h4 id="orgeac0874">Clarification</h4>
<div class="outline-text-4" id="text-orgeac0874">
<p>
Translate obscure values into readable terms.
</p>
<p>
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">
<p>
Alert others about performance, thread-safety, or side effects.
</p>
<p>
For example, in code you can say:
</p>
<p>
<code>// SimpleDateFormat is not thread safe, so create each instance independently.</code>
</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">
<p>
Mark incomplete work or planned improvements.
</p>
<p>
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">
<p>
Highlight the importance of seemingly small details.
</p>
<p>
<code>// the trim is real important. It removes starting spaces...</code>
</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">
<p>
Public APIs should have clear documentation.
</p>
<p>
Javadocs can also mislead. Keep them accurate and up-to-date.
</p>
</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">
<ul class="org-ul">
<li>Don't place a comment just because you feel like it.</li>
<li>Remove redundant comments.</li>
<li>Avoid misleading comments.</li>
<li>Don't mandate everything (not every function needs a Javadoc).</li>
<li>No need for journal comments, we have source control.</li>
<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">
<p>
Replace explanatory comments with expressive variable or function names.
</p>
<p>
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">
<p>
Avoid decorative banners like <code>// Actions ///////////////////////</code>, they add clutter.
</p>
<p>
Use sparingly and only for meaningful grouping.
</p>
<p>
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">
<p>
Comments on closing braces (} // while) are unnecessary for small, well structured functions.
</p>
<p>
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">
<p>
Don’t add personal tags like <code>/* Added by Rick */</code>, use version control for authorship history.
</p>
<p>
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">
<p>
Never keep old code commented out; delete it and rely on version control history.
</p>
<p>
Commented-out code adds clutter and confuses future maintainers.
</p>
<div class="org-src-container">
<pre class="src src-java">
<span class="org-comment-delimiter">// </span><span class="org-comment">Old cruft that should be deleted:
</span><span class="org-comment-delimiter">//</span><span class="org-comment">hdrPos = bytePos;
</span><span class="org-comment-delimiter">//</span><span class="org-comment">dataPos = bytePos;
</span>
</pre>
</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">
<p>
Avoid HTML markup inside code comments, it makes them harder to read in the editor.
</p>
<p>
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">
<p>
Comments should describe nearby code only, not unrelated parts of the system.
</p>
<p>
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">
<p>
Avoid long, unnecessary historical or technical explanations.
</p>
<p>
Keep only relevant context (e.g., “RFC 2045” reference is fine, not the full spec).
</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">
<p>
Ensure the relationship between comment and code is clear.
</p>
<p>
Don’t make readers guess what part of the code the comment refers to.
</p>
<div class="org-src-container">
<pre class="src src-java">
<span class="org-comment-delimiter">// </span><span class="org-comment">plus filter bytes ... but which part is &#8220;filter&#8221;?
</span><span class="org-keyword">this</span>.pngBytes = <span class="org-keyword">new</span> <span class="org-type">byte</span>[((<span class="org-keyword">this</span>.width + 1) * <span class="org-keyword">this</span>.height * 3) + 200];
</pre>
</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">
<p>
Short, single purpose functions with good names don’t need header comments.
</p>
<p>
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">
<p>
Javadocs are useful for public APIs, but excessive formality in internal code is just noise.
</p>
<p>
Internal methods should be self explanatory without full doc comments.
</p>
</div>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<footer>
<div class="copyright-container">
<div class="copyright">
Copyright &copy; 2022-2025 Zaine Qayyum. All rights reserved unless otherwise noted.</div></div>
<div class="generated">
Created with <a href="https://www.gnu.org/software/emacs/">Emacs</a> 30.1 (<a href="https://orgmode.org">Org</a> mode 9.7.11) on <a href="https://www.archlinux.org/">Arch</a> <a href="https://www.gnu.org">GNU</a>/<a href="https://www.kernel.org/">Linux</a>
</div>
</footer>
</div>
</body>
</html>

560
output/posts/clean-code/clean-code-chapter-5.html Normal file
View File

@@ -0,0 +1,560 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"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 -->
<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 5 Notes</title>
<meta name="generator" content="Org Mode" />
<style type="text/css">
#content { max-width: 60em; margin: auto; }
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #e6e6e6;
border-radius: 3px;
background-color: #f2f2f2;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: auto;
}
pre.src:before {
display: none;
position: absolute;
top: -8px;
right: 12px;
padding: 3px;
color: #555;
background-color: #f2f2f299;
}
pre.src:hover:before { display: inline; margin-top: 14px;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-authinfo::before { content: 'Authinfo'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { }
</style>
<link rel="stylesheet" href="/assets/styles/style.css" />
<link rel="stylesheet" href="/assets/styles/bigger-picture.min.css" />
<script src="/assets/scripts/script.js" defer></script>
<script src="/assets/scripts/bigger-picture.min.js" defer></script>
<script src="/assets/scripts/svg-pan-zoom.min.js" defer></script>
<script src="/assets/scripts/gallery-init.js" defer></script>
</head>
<body>
<div id="preamble" class="status">
<div class="banner-header">
<a href="/"> <img src="/assets/images/gr.png" alt="Site Logo" class="banner-logo" /> </a>
<nav>
<a href="/">Home | </a>
<a href="/posts/posts-list.html">Posts | </a>
<a href="/blogs/blogs-list.html">Blogs | </a>
<a href="/contact.html">Contact</a>
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-28 Thu 17:03</div>
</div>
<div id="content" class="content">
<h1 class="title">Clean Code: Chapter 5 Notes</h1>
<div class="filetags"><a href="/categories.html"> <span class="post-tag">books</span> </a> <a href="/categories.html"> <span class="post-tag">notes</span> </a></div>
<div id="table-of-contents" role="doc-toc">
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orgf6788d4">Chapter 5: Formatting</a>
<ul>
<li><a href="#org28e2157">Vertical Formatting</a>
<ul>
<li><a href="#orga4fe877">Vertical Density</a></li>
<li><a href="#orgd65a796">Vertical Distance</a></li>
<li><a href="#orgc7e60d5">Conceptual Affinity</a></li>
<li><a href="#org8209321">Vertical Ordering</a></li>
<li><a href="#org1145f8a">Summary - vertical</a></li>
</ul>
</li>
<li><a href="#org204eeff">Horizontal Formatting</a>
<ul>
<li><a href="#orgcce3495">Horizontal Openness and Density</a></li>
<li><a href="#orgfdedcbd">Horizontal Alignment</a></li>
<li><a href="#org5ea9f27">Indentation</a></li>
<li><a href="#org0a1acdf">Dummy Scopes</a></li>
</ul>
</li>
<li><a href="#orgec702a7">Team Rules</a></li>
<li><a href="#org2d58312">Uncle Bob’s Formatting Rules (Example in CodeAnalyzer.java)</a></li>
</ul>
</li>
</ul>
</div>
</div>
<p>
Link to <a href="clean-code-chapter-4.html">Chapter 4</a> | Link to <a href="clean-code-chapter-6.html">Chapter 6</a>
</p>
<div id="outline-container-orgf6788d4" class="outline-2">
<h2 id="orgf6788d4">Chapter 5: Formatting</h2>
<div class="outline-text-2" id="text-orgf6788d4">
</div>
<div id="outline-container-org28e2157" class="outline-3">
<h3 id="org28e2157">Vertical Formatting</h3>
<div class="outline-text-3" id="text-org28e2157">
<ul class="org-ul">
<li>Vertical openness (blank lines) separates concepts and improves readability.</li>
<li>Too much density makes code look like a muddle and harder to scan.</li>
</ul>
</div>
<div id="outline-container-orga4fe877" class="outline-4">
<h4 id="orga4fe877">Vertical Density</h4>
<div class="outline-text-4" id="text-orga4fe877">
<ul class="org-ul">
<li>Tightly related lines should appear vertically dense.</li>
<li>Avoid useless comments that interrupt association.</li>
<li>Example (bad):</li>
</ul>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">public</span> <span class="org-keyword">class</span> <span class="org-type">ReporterConfig</span> {
<span class="org-doc">/**
* The class name of the reporter listener
*/</span>
<span class="org-keyword">private</span> <span class="org-type">String</span> <span class="org-variable-name">m_className</span>;
</pre>
</div>
<ul class="org-ul">
<li>Example (better):</li>
</ul>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">public</span> <span class="org-keyword">class</span> <span class="org-type">ReporterConfig</span> {
<span class="org-keyword">private</span> <span class="org-type">String</span> <span class="org-variable-name">m_className</span>;
<span class="org-keyword">private</span> <span class="org-type">List</span>&lt;<span class="org-type">Property</span>&gt; <span class="org-variable-name">m_properties</span> = <span class="org-keyword">new</span> <span class="org-type">ArrayList</span>&lt;&gt;();
</pre>
</div>
</div>
</div>
<div id="outline-container-orgd65a796" class="outline-4">
<h4 id="orgd65a796">Vertical Distance</h4>
<div class="outline-text-4" id="text-orgd65a796">
<ul class="org-ul">
<li>Related concepts should be kept close together to reduce scrolling and searching.</li>
<li>Local variables → as close to use as possible, usually at top of function.</li>
<li>Control variables → declared inside loop headers.</li>
<li>Instance variables → declared at the top of class (common Java convention).</li>
</ul>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">for</span> (<span class="org-type">Test</span> <span class="org-variable-name">each</span> : tests) {
count += each.countTestCases();
}
</pre>
</div>
<ul class="org-ul">
<li>Dependent functions: caller above callee for natural top-down reading.</li>
</ul>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">public</span> <span class="org-type">Response</span> <span class="org-function-name">makeResponse</span>(...) {
<span class="org-type">String</span> <span class="org-variable-name">pageName</span> = getPageNameOrDefault(request, <span class="org-string">"FrontPage"</span>);
loadPage(pageName, context);
<span class="org-keyword">return</span> makePageResponse(context);
}
<span class="org-keyword">private</span> <span class="org-type">String</span> <span class="org-function-name">getPageNameOrDefault</span>(<span class="org-type">Request</span> <span class="org-variable-name">request</span>, <span class="org-type">String</span> <span class="org-variable-name">defaultPageName</span>) { ... }
</pre>
</div>
</div>
</div>
<div id="outline-container-orgc7e60d5" class="outline-4">
<h4 id="orgc7e60d5">Conceptual Affinity</h4>
<div class="outline-text-4" id="text-orgc7e60d5">
<ul class="org-ul">
<li>Group functions with similar naming or shared purpose.</li>
<li>Example (JUnit assert methods):</li>
</ul>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">static</span> <span class="org-keyword">public</span> <span class="org-type">void</span> <span class="org-function-name">assertTrue</span>(<span class="org-type">String</span> <span class="org-variable-name">message</span>, <span class="org-type">boolean</span> <span class="org-variable-name">condition</span>) { ... }
<span class="org-keyword">static</span> <span class="org-keyword">public</span> <span class="org-type">void</span> <span class="org-function-name">assertTrue</span>(<span class="org-type">boolean</span> <span class="org-variable-name">condition</span>) { ... }
<span class="org-keyword">static</span> <span class="org-keyword">public</span> <span class="org-type">void</span> <span class="org-function-name">assertFalse</span>(<span class="org-type">String</span> <span class="org-variable-name">message</span>, <span class="org-type">boolean</span> <span class="org-variable-name">condition</span>) { ... }
<span class="org-keyword">static</span> <span class="org-keyword">public</span> <span class="org-type">void</span> <span class="org-function-name">assertFalse</span>(<span class="org-type">boolean</span> <span class="org-variable-name">condition</span>) { ... }
</pre>
</div>
</div>
</div>
<div id="outline-container-org8209321" class="outline-4">
<h4 id="org8209321">Vertical Ordering</h4>
<div class="outline-text-4" id="text-org8209321">
<ul class="org-ul">
<li>Organise code top down:
<ul class="org-ul">
<li>High-level concepts first (main logic).</li>
<li>Lower-level details later.</li>
</ul></li>
<li>Readers can skim like a newspaper: important first, details last.</li>
<li>Contrast: C/C++ require declarations before use, Java does not.</li>
</ul>
</div>
</div>
<div id="outline-container-org1145f8a" class="outline-4">
<h4 id="org1145f8a">Summary - vertical</h4>
<div class="outline-text-4" id="text-org1145f8a">
<ul class="org-ul">
<li>Use vertical openness to separate concepts.</li>
<li>Use vertical density to group related ones.</li>
<li>Keep related variables, methods, and concepts close together.</li>
<li>Order code top down for natural readability.</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-org204eeff" class="outline-3">
<h3 id="org204eeff">Horizontal Formatting</h3>
<div class="outline-text-3" id="text-org204eeff">
<p>
Keep lines short. Most professional code naturally stays within ~45 characters, with ~80 as an upper bound. Lines beyond 100–120 characters are generally careless.
</p>
<p>
Avoid shrinking font or overly wide monitors to fit more code, readability &gt; fitting more characters.
</p>
<p>
Example limit guideline:
</p>
<div class="org-src-container">
<pre class="src src-java"><span class="org-comment-delimiter">// </span><span class="org-comment">Good (short)
</span><span class="org-type">int</span> <span class="org-variable-name">sum</span> = a + b + c;
<span class="org-comment-delimiter">// </span><span class="org-comment">Bad (too long)
</span><span class="org-type">int</span> <span class="org-variable-name">sum</span> = a + b + c + d + e + f + g + h + i + j + k + l + m + n + o + p + q;
</pre>
</div>
</div>
<div id="outline-container-orgcce3495" class="outline-4">
<h4 id="orgcce3495">Horizontal Openness and Density</h4>
<div class="outline-text-4" id="text-orgcce3495">
<p>
Use spaces to separate low-precedence operators (e.g., +, -, =) and improve readability.
</p>
<p>
Do not put spaces between function names and parentheses, they are closely related.
</p>
<p>
Example (Quadratic formula formatting):
</p>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">return</span> (-b + Math.sqrt(determinant)) / (2*a);
</pre>
</div>
<p>
Separate arguments with spaces after commas to show distinct parameters.
</p>
</div>
</div>
<div id="outline-container-orgfdedcbd" class="outline-4">
<h4 id="orgfdedcbd">Horizontal Alignment</h4>
<div class="outline-text-4" id="text-orgfdedcbd">
<p>
Avoid aligning variable declarations or assignments in columns, it draws the eye to the wrong place.
</p>
<p>
Long aligned lists usually mean the class is too large and should be split.
</p>
<p>
Example (preferred unaligned):
</p>
<div class="org-src-container">
<pre class="src src-java"><span class="org-comment-delimiter">// </span><span class="org-comment">Prefer this:
</span><span class="org-keyword">private</span> <span class="org-type">Socket</span> <span class="org-variable-name">socket</span>;
<span class="org-keyword">private</span> <span class="org-type">InputStream</span> <span class="org-variable-name">input</span>;
<span class="org-keyword">private</span> <span class="org-type">OutputStream</span> <span class="org-variable-name">output</span>;
<span class="org-comment-delimiter">//</span><span class="org-comment">instead of:
</span><span class="org-keyword">private</span> <span class="org-type">Socket</span> <span class="org-variable-name">socket</span>;
<span class="org-keyword">private</span> <span class="org-type">InputStream</span> <span class="org-variable-name">input</span>;
<span class="org-keyword">private</span> <span class="org-type">OutputStream</span> <span class="org-variable-name">output</span>;
</pre>
</div>
</div>
</div>
<div id="outline-container-org5ea9f27" class="outline-4">
<h4 id="org5ea9f27">Indentation</h4>
<div class="outline-text-4" id="text-org5ea9f27">
<p>
Indent according to scope hierarchy:
</p>
<p>
Classes → no indent
</p>
<p>
Methods → 1 level
</p>
<p>
Method bodies → 2 levels
</p>
<p>
Inner blocks → +1 for each nesting
</p>
<p>
Indentation makes scopes visually obvious; without it, code is hard to scan.
</p>
<p>
Avoid collapsing scopes onto one line, always use braces and proper indenting.
</p>
</div>
</div>
<div id="outline-container-org0a1acdf" class="outline-4">
<h4 id="org0a1acdf">Dummy Scopes</h4>
<div class="outline-text-4" id="text-org0a1acdf">
<p>
Avoid dummy bodies in loops (e.g., empty while or for loops).
</p>
<p>
If unavoidable, place semicolon on its own indented line to make it visible.
</p>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">while</span> (dis.read(buf, 0, size) != -1)
;
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-orgec702a7" class="outline-3">
<h3 id="orgec702a7">Team Rules</h3>
<div class="outline-text-3" id="text-orgec702a7">
<p>
Teams must agree on a single formatting style for consistency.
</p>
<p>
Use IDE formatters to enforce these rules across all files.
</p>
<p>
Consistent formatting builds trust and reduces mental load for readers.
</p>
</div>
</div>
<div id="outline-container-org2d58312" class="outline-3">
<h3 id="org2d58312">Uncle Bob’s Formatting Rules (Example in CodeAnalyzer.java)</h3>
<div class="outline-text-3" id="text-org2d58312">
<p>
Short, clear methods with consistent spacing and indentation.
</p>
<p>
Use spaces around assignment and low-precedence operators, no space for high precedence operators.
</p>
<p>
Avoid deeply nested structures. Prefer clear, flat logic.
</p>
<p>
Example snippet:
</p>
<div class="org-src-container">
<pre class="src src-java"><span class="org-keyword">private</span> <span class="org-type">void</span> <span class="org-function-name">measureLine</span>(<span class="org-type">String</span> <span class="org-variable-name">line</span>) {
lineCount++;
<span class="org-type">int</span> <span class="org-variable-name">lineSize</span> = line.length();
totalChars += lineSize;
lineWidthHistogram.addLine(lineSize, lineCount);
recordWidestLine(lineSize);
}
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<footer>
<div class="copyright-container">
<div class="copyright">
Copyright &copy; 2022-2025 Zaine Qayyum. All rights reserved unless otherwise noted.</div></div>
<div class="generated">
Created with <a href="https://www.gnu.org/software/emacs/">Emacs</a> 30.1 (<a href="https://orgmode.org">Org</a> mode 9.7.11) on <a href="https://www.archlinux.org/">Arch</a> <a href="https://www.gnu.org">GNU</a>/<a href="https://www.kernel.org/">Linux</a>
</div>
</footer>
</div>
</body>
</html>

8
output/posts/posts-intro.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-27 Wed 22:32 -->
<!-- 2025-08-28 Thu 17:03 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Posts Introduction</title>
@@ -220,9 +220,9 @@
<h1 class="title">Posts Introduction</h1>
<div class="filetags"><a href="/categories.html"> <span class="post-tag">introduction</span> </a></div>
<div id="outline-container-orgb7165f8" class="outline-2">
<h2 id="orgb7165f8">Introduction</h2>
<div class="outline-text-2" id="text-orgb7165f8">
<div id="outline-container-orgf530991" class="outline-2">
<h2 id="orgf530991">Introduction</h2>
<div class="outline-text-2" id="text-orgf530991">
<p>
In this section you will find posts related to both technical and non-technical topics. As Einstein said: “If you can’t explain it simply you don’t understand it well enough”, thus the goal with these <code>posts</code> is to develop the skill of being able to deliver habitual high quality explanations as well as reinforcing the topic(s) learnt.
</p>

12
output/posts/posts-list.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-27 Wed 22:32 -->
<!-- 2025-08-28 Thu 17:03 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Posts List</title>
@@ -214,17 +214,19 @@
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-27 Wed 22:32</div>
<div id="updated">Updated: 2025-08-28 Thu 17:03</div>
</div>
<div id="content" class="content">
<h1 class="title">Posts List</h1>
<p>
See the categories: <a href="../categories.html">Categories</a>
</p>
<div id="outline-container-orgaf4f59f" class="outline-2">
<h2 id="orgaf4f59f">Posts:</h2>
<div class="outline-text-2" id="text-orgaf4f59f">
<div id="outline-container-org14b5d54" class="outline-2">
<h2 id="org14b5d54">Posts:</h2>
<div class="outline-text-2" id="text-org14b5d54">
<ul class="org-ul">
<li><a href="clean-code/clean-code-chapter-5.html">Clean Code: Chapter 5 Notes</a> <span class="post-date">28-08-2025 17:03</span> <a href="/tags/books.html"> <span class="post-tag">books</span> </a> <a href="/tags/notes.html"> <span class="post-tag">notes</span> </a></li>
<li><a href="clean-code/clean-code-chapter-4.html">Clean Code: Chapter 4 Notes</a> <span class="post-date">28-08-2025 16:38</span> <a href="/tags/books.html"> <span class="post-tag">books</span> </a> <a href="/tags/notes.html"> <span class="post-tag">notes</span> </a></li>
<li><a href="clean-code/clean-code-chapter-3.html">Clean Code: Chapter 3 Notes</a> <span class="post-date">12-08-2025 18:30</span> <a href="/tags/books.html"> <span class="post-tag">books</span> </a> <a href="/tags/notes.html"> <span class="post-tag">notes</span> </a></li>
<li><a href="clean-code/clean-code-chapter-2.html">Clean Code: Chapter 2 Notes</a> <span class="post-date">10-08-2025 20:00</span> <a href="/tags/books.html"> <span class="post-tag">books</span> </a> <a href="/tags/notes.html"> <span class="post-tag">notes</span> </a></li>
<li><a href="clean-code/clean-code-chapter-1.html">Clean Code: Chapter 1 Notes</a> <span class="post-date">10-08-2025 19:45</span> <a href="/tags/books.html"> <span class="post-tag">books</span> </a> <a href="/tags/notes.html"> <span class="post-tag">notes</span> </a></li>