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

Auto-publish on Tue 19 Aug 17:37:17 BST 2025

Browse Source
This commit is contained in:
Zaine Arch
2025-08-19 17:37:17 +01:00
parent 58303320c0
commit d398462161
33 changed files with 592 additions and 290 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-14 Thu 23:51 -->
<!-- 2025-08-19 Tue 17:37 -->
<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="#orga5edbea">Chapter 1: Clean Code</a></li>
<li><a href="#org2950e83">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-orga5edbea" class="outline-2">
<h2 id="orga5edbea">Chapter 1: Clean Code</h2>
<div class="outline-text-2" id="text-orga5edbea">
<div id="outline-container-org2950e83" class="outline-2">
<h2 id="org2950e83">Chapter 1: Clean Code</h2>
<div class="outline-text-2" id="text-org2950e83">
<p>
Referenced Items:
</p>

122
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-14 Thu 23:51 -->
<!-- 2025-08-19 Tue 17:37 -->
<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>
@@ -224,22 +224,22 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orgf9287f4">Chapter 2: Meaningful Names</a>
<li><a href="#org1a3408a">Chapter 2: Meaningful Names</a>
<ul>
<li><a href="#org3be2aad">Use intention revealing names:</a></li>
<li><a href="#orgb7762a7">Avoid disinformation</a></li>
<li><a href="#orgd96c275">Make Meaningful Distinctions</a></li>
<li><a href="#org885f55a">Use Pronouncable Names</a></li>
<li><a href="#org6fd704d">Use Searchable Names</a></li>
<li><a href="#org1413ea3">Avoid Encodings</a></li>
<li><a href="#orgb8dd4dc">Avoid Mental Mappings</a></li>
<li><a href="#org8519f0a">Class Names</a></li>
<li><a href="#org98766ad">Method Names</a></li>
<li><a href="#org6a7f147">Don't be cute/Don't use puns</a></li>
<li><a href="#org0bdcaa8">Pick one word per concept</a></li>
<li><a href="#org4f20c44">Solution Domain Names and Problem Domain Names</a></li>
<li><a href="#orge01da79">Add Meaningful Context</a></li>
<li><a href="#org4bac65c">Don't add gratuitous context</a></li>
<li><a href="#orgf8d8f8c">Use intention revealing names:</a></li>
<li><a href="#orgdcbb68c">Avoid disinformation</a></li>
<li><a href="#org8fcf195">Make Meaningful Distinctions</a></li>
<li><a href="#orgfaff4c1">Use Pronouncable Names</a></li>
<li><a href="#org6fd12d6">Use Searchable Names</a></li>
<li><a href="#org39c47aa">Avoid Encodings</a></li>
<li><a href="#org7fbe5c0">Avoid Mental Mappings</a></li>
<li><a href="#orgfc91f36">Class Names</a></li>
<li><a href="#orgb759d16">Method Names</a></li>
<li><a href="#org51364bc">Don't be cute/Don't use puns</a></li>
<li><a href="#org4fd660a">Pick one word per concept</a></li>
<li><a href="#org7f235ac">Solution Domain Names and Problem Domain Names</a></li>
<li><a href="#orgc951ae5">Add Meaningful Context</a></li>
<li><a href="#org79fce80">Don't add gratuitous context</a></li>
</ul>
</li>
</ul>
@@ -249,13 +249,13 @@
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-orgf9287f4" class="outline-2">
<h2 id="orgf9287f4">Chapter 2: Meaningful Names</h2>
<div class="outline-text-2" id="text-orgf9287f4">
<div id="outline-container-org1a3408a" class="outline-2">
<h2 id="org1a3408a">Chapter 2: Meaningful Names</h2>
<div class="outline-text-2" id="text-org1a3408a">
</div>
<div id="outline-container-org3be2aad" class="outline-3">
<h3 id="org3be2aad">Use intention revealing names:</h3>
<div class="outline-text-3" id="text-org3be2aad">
<div id="outline-container-orgf8d8f8c" class="outline-3">
<h3 id="orgf8d8f8c">Use intention revealing names:</h3>
<div class="outline-text-3" id="text-orgf8d8f8c">
<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 +268,17 @@ Names should reveal intent, there is no revelation in naming an integer <code>d<
</div>
</div>
</div>
<div id="outline-container-orgb7762a7" class="outline-3">
<h3 id="orgb7762a7">Avoid disinformation</h3>
<div class="outline-text-3" id="text-orgb7762a7">
<div id="outline-container-orgdcbb68c" class="outline-3">
<h3 id="orgdcbb68c">Avoid disinformation</h3>
<div class="outline-text-3" id="text-orgdcbb68c">
<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-orgd96c275" class="outline-3">
<h3 id="orgd96c275">Make Meaningful Distinctions</h3>
<div class="outline-text-3" id="text-orgd96c275">
<div id="outline-container-org8fcf195" class="outline-3">
<h3 id="org8fcf195">Make Meaningful Distinctions</h3>
<div class="outline-text-3" id="text-org8fcf195">
<p>
While it is possible to name by being disinformative, it is also possible to name being non informative. Consider:
</p>
@@ -303,18 +303,18 @@ Furthermore, noise words are redundant. We should never use the word <code>varia
</p>
</div>
</div>
<div id="outline-container-org885f55a" class="outline-3">
<h3 id="org885f55a">Use Pronouncable Names</h3>
<div class="outline-text-3" id="text-org885f55a">
<div id="outline-container-orgfaff4c1" class="outline-3">
<h3 id="orgfaff4c1">Use Pronouncable Names</h3>
<div class="outline-text-3" id="text-orgfaff4c1">
<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-org6fd704d" class="outline-3">
<h3 id="org6fd704d">Use Searchable Names</h3>
<div class="outline-text-3" id="text-org6fd704d">
<div id="outline-container-org6fd12d6" class="outline-3">
<h3 id="org6fd12d6">Use Searchable Names</h3>
<div class="outline-text-3" id="text-org6fd12d6">
<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 +324,42 @@ In modern IDE's, it is still quite difficult to search for single-lettered varia
</p>
</div>
</div>
<div id="outline-container-org1413ea3" class="outline-3">
<h3 id="org1413ea3">Avoid Encodings</h3>
<div class="outline-text-3" id="text-org1413ea3">
<div id="outline-container-org39c47aa" class="outline-3">
<h3 id="org39c47aa">Avoid Encodings</h3>
<div class="outline-text-3" id="text-org39c47aa">
<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-orgb8dd4dc" class="outline-3">
<h3 id="orgb8dd4dc">Avoid Mental Mappings</h3>
<div class="outline-text-3" id="text-orgb8dd4dc">
<div id="outline-container-org7fbe5c0" class="outline-3">
<h3 id="org7fbe5c0">Avoid Mental Mappings</h3>
<div class="outline-text-3" id="text-org7fbe5c0">
<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-org8519f0a" class="outline-3">
<h3 id="org8519f0a">Class Names</h3>
<div class="outline-text-3" id="text-org8519f0a">
<div id="outline-container-orgfc91f36" class="outline-3">
<h3 id="orgfc91f36">Class Names</h3>
<div class="outline-text-3" id="text-orgfc91f36">
<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-org98766ad" class="outline-3">
<h3 id="org98766ad">Method Names</h3>
<div class="outline-text-3" id="text-org98766ad">
<div id="outline-container-orgb759d16" class="outline-3">
<h3 id="orgb759d16">Method Names</h3>
<div class="outline-text-3" id="text-orgb759d16">
<p>
Methods should have verb or verb phrase names.
</p>
</div>
</div>
<div id="outline-container-org6a7f147" class="outline-3">
<h3 id="org6a7f147">Don't be cute/Don't use puns</h3>
<div class="outline-text-3" id="text-org6a7f147">
<div id="outline-container-org51364bc" class="outline-3">
<h3 id="org51364bc">Don't be cute/Don't use puns</h3>
<div class="outline-text-3" id="text-org51364bc">
<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 +369,17 @@ Do not use names that are only understandable to people whom you share jokes etc
</ul>
</div>
</div>
<div id="outline-container-org0bdcaa8" class="outline-3">
<h3 id="org0bdcaa8">Pick one word per concept</h3>
<div class="outline-text-3" id="text-org0bdcaa8">
<div id="outline-container-org4fd660a" class="outline-3">
<h3 id="org4fd660a">Pick one word per concept</h3>
<div class="outline-text-3" id="text-org4fd660a">
<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-org4f20c44" class="outline-3">
<h3 id="org4f20c44">Solution Domain Names and Problem Domain Names</h3>
<div class="outline-text-3" id="text-org4f20c44">
<div id="outline-container-org7f235ac" class="outline-3">
<h3 id="org7f235ac">Solution Domain Names and Problem Domain Names</h3>
<div class="outline-text-3" id="text-org7f235ac">
<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 +389,17 @@ However when it is not possible to use solution domain names (in other words, wh
</p>
</div>
</div>
<div id="outline-container-orge01da79" class="outline-3">
<h3 id="orge01da79">Add Meaningful Context</h3>
<div class="outline-text-3" id="text-orge01da79">
<div id="outline-container-orgc951ae5" class="outline-3">
<h3 id="orgc951ae5">Add Meaningful Context</h3>
<div class="outline-text-3" id="text-orgc951ae5">
<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-org4bac65c" class="outline-3">
<h3 id="org4bac65c">Don't add gratuitous context</h3>
<div class="outline-text-3" id="text-org4bac65c">
<div id="outline-container-org79fce80" class="outline-3">
<h3 id="org79fce80">Don't add gratuitous context</h3>
<div class="outline-text-3" id="text-org79fce80">
<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>

66
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-14 Thu 23:51 -->
<!-- 2025-08-19 Tue 17:37 -->
<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>
@@ -224,15 +224,15 @@
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orgb91b4dc">Chapter 3: Functions</a>
<li><a href="#orgdaf7681">Chapter 3: Functions</a>
<ul>
<li><a href="#orgcdb13f4">Functions should be small</a></li>
<li><a href="#orgeffdad8">Do One Thing &amp; One Level of Abstraction</a></li>
<li><a href="#org2a991c8">Switch Statements</a></li>
<li><a href="#org7381d04">Use Descriptive Names</a></li>
<li><a href="#orga806b6f">Function Arguments</a></li>
<li><a href="#orgebcce67">Have No Side Effects</a></li>
<li><a href="#org77d704a">Error Handling</a></li>
<li><a href="#orgc933663">Functions should be small</a></li>
<li><a href="#orgc6ef870">Do One Thing &amp; One Level of Abstraction</a></li>
<li><a href="#org58e6c35">Switch Statements</a></li>
<li><a href="#orgc7a05f3">Use Descriptive Names</a></li>
<li><a href="#org1900efd">Function Arguments</a></li>
<li><a href="#org9c9b361">Have No Side Effects</a></li>
<li><a href="#org56f50e7">Error Handling</a></li>
</ul>
</li>
</ul>
@@ -241,13 +241,13 @@
<p>
Link to <a href="clean-code-chapter-2.html">Chapter 2</a>
</p>
<div id="outline-container-orgb91b4dc" class="outline-2">
<h2 id="orgb91b4dc">Chapter 3: Functions</h2>
<div class="outline-text-2" id="text-orgb91b4dc">
<div id="outline-container-orgdaf7681" class="outline-2">
<h2 id="orgdaf7681">Chapter 3: Functions</h2>
<div class="outline-text-2" id="text-orgdaf7681">
</div>
<div id="outline-container-orgcdb13f4" class="outline-3">
<h3 id="orgcdb13f4">Functions should be small</h3>
<div class="outline-text-3" id="text-orgcdb13f4">
<div id="outline-container-orgc933663" class="outline-3">
<h3 id="orgc933663">Functions should be small</h3>
<div class="outline-text-3" id="text-orgc933663">
<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-orgeffdad8" class="outline-3">
<h3 id="orgeffdad8">Do One Thing &amp; One Level of Abstraction</h3>
<div class="outline-text-3" id="text-orgeffdad8">
<div id="outline-container-orgc6ef870" class="outline-3">
<h3 id="orgc6ef870">Do One Thing &amp; One Level of Abstraction</h3>
<div class="outline-text-3" id="text-orgc6ef870">
<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-org2a991c8" class="outline-3">
<h3 id="org2a991c8">Switch Statements</h3>
<div class="outline-text-3" id="text-org2a991c8">
<div id="outline-container-org58e6c35" class="outline-3">
<h3 id="org58e6c35">Switch Statements</h3>
<div class="outline-text-3" id="text-org58e6c35">
<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-org7381d04" class="outline-3">
<h3 id="org7381d04">Use Descriptive Names</h3>
<div class="outline-text-3" id="text-org7381d04">
<div id="outline-container-orgc7a05f3" class="outline-3">
<h3 id="orgc7a05f3">Use Descriptive Names</h3>
<div class="outline-text-3" id="text-orgc7a05f3">
<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-orga806b6f" class="outline-3">
<h3 id="orga806b6f">Function Arguments</h3>
<div class="outline-text-3" id="text-orga806b6f">
<div id="outline-container-org1900efd" class="outline-3">
<h3 id="org1900efd">Function Arguments</h3>
<div class="outline-text-3" id="text-org1900efd">
<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-orgebcce67" class="outline-3">
<h3 id="orgebcce67">Have No Side Effects</h3>
<div class="outline-text-3" id="text-orgebcce67">
<div id="outline-container-org9c9b361" class="outline-3">
<h3 id="org9c9b361">Have No Side Effects</h3>
<div class="outline-text-3" id="text-org9c9b361">
<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-org77d704a" class="outline-3">
<h3 id="org77d704a">Error Handling</h3>
<div class="outline-text-3" id="text-org77d704a">
<div id="outline-container-org56f50e7" class="outline-3">
<h3 id="org56f50e7">Error Handling</h3>
<div class="outline-text-3" id="text-org56f50e7">
<p>
Error handling is a single responsibility—separate it from normal logic to keep both paths clear.
</p>

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-14 Thu 23:51 -->
<!-- 2025-08-19 Tue 17:37 -->
<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-org0726d72" class="outline-2">
<h2 id="org0726d72">Introduction</h2>
<div class="outline-text-2" id="text-org0726d72">
<div id="outline-container-org2532af6" class="outline-2">
<h2 id="org2532af6">Introduction</h2>
<div class="outline-text-2" id="text-org2532af6">
<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>

10
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-14 Thu 23:51 -->
<!-- 2025-08-19 Tue 17:37 -->
<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,16 +214,16 @@
</nav>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle dark mode">🌗 Theme</button>
</div>
<div id="updated">Updated: 2025-08-14 Thu 23:51</div>
<div id="updated">Updated: 2025-08-19 Tue 17:37</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-orgced4e00" class="outline-2">
<h2 id="orgced4e00">Posts:</h2>
<div class="outline-text-2" id="text-orgced4e00">
<div id="outline-container-org02a2aa2" class="outline-2">
<h2 id="org02a2aa2">Posts:</h2>
<div class="outline-text-2" id="text-org02a2aa2">
<ul class="org-ul">
<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>