From 04f85387543e30ad1c4a8c539b9ebffecb5cafc9 Mon Sep 17 00:00:00 2001 From: Zaine Arch Date: Thu, 28 Aug 2025 17:04:32 +0100 Subject: [PATCH] Auto-publish on Thu 28 Aug 17:04:32 BST 2025 --- output/about.html | 8 +- output/blogs/2025/08/benefits-of-reading.html | 50 +- output/blogs/2025/08/hilberts.hotel.html | 2 +- ...pending-the-whole-day-on-this-website.html | 8 +- output/blogs/2025/08/wacom-with-arch.html | 8 +- ...kly-review-week-ending-august-10-2025.html | 54 +- ...kly-review-week-ending-august-17-2025.html | 78 +-- ...kly-review-week-ending-august-24-2025.html | 28 +- .../08/what-do-i-want-to-do-with-emacs.html | 4 +- output/blogs/2025/08/zettelkasten.html | 10 +- output/blogs/blogs-intro.html | 8 +- output/blogs/blogs-list.html | 10 +- output/categories.html | 14 +- output/contact.html | 8 +- output/index.html | 26 +- output/posts.html | 18 +- .../clean-code/clean-code-chapter-1.html | 10 +- .../clean-code/clean-code-chapter-2.html | 127 ++-- .../clean-code/clean-code-chapter-3.html | 70 +- .../clean-code/clean-code-chapter-4.html | 618 ++++++++++++++++++ .../clean-code/clean-code-chapter-5.html | 560 ++++++++++++++++ output/posts/posts-intro.html | 8 +- output/posts/posts-list.html | 12 +- output/setup.html | 20 +- output/sitemap.html | 10 +- output/tags/books.html | 12 +- output/tags/education.html | 10 +- output/tags/emacs.html | 10 +- output/tags/insights.html | 10 +- output/tags/introduction.html | 10 +- output/tags/maths.html | 10 +- output/tags/notes.html | 12 +- output/tags/reading.html | 10 +- output/tags/review.html | 10 +- output/tags/website.html | 10 +- output/tags/weekly-review.html | 10 +- 36 files changed, 1534 insertions(+), 349 deletions(-) create mode 100644 output/posts/clean-code/clean-code-chapter-4.html create mode 100644 output/posts/clean-code/clean-code-chapter-5.html diff --git a/output/about.html b/output/about.html index 90d7310..90d9dee 100644 --- a/output/about.html +++ b/output/about.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + About Page @@ -217,9 +217,9 @@
Updated: 2025-08-08 Fri 23:07
-
-

About

-
+
+

About

+

TODO

diff --git a/output/blogs/2025/08/benefits-of-reading.html b/output/blogs/2025/08/benefits-of-reading.html index b66f2e5..e55a911 100644 --- a/output/blogs/2025/08/benefits-of-reading.html +++ b/output/blogs/2025/08/benefits-of-reading.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Benefits of Reading @@ -224,60 +224,60 @@

Table of Contents

-
-

Benefits 1

-
+
+

Benefits 1

+

At times, I find myself being able to digest material more quickly and efficiently, and so I thought to myself as to what the probable cause of this was. The answer transpired to be the inculcating of reading in my daily routine. As humans, we are constantly surrounded with information, some are noisy, some are useful. We can choose to filter out noisy information by limiting exposure of their avenues, however the topic I wanted to briefly touch upon is what are the (cognitive and non-cognitive) benefits of increasing the intake of useful information through the medium of reading?

-
-

Mental Stimulation

-
+
+

Mental Stimulation

+

The brain is a muscle, in order to keep any muscle strong and healthy, it needs stimulation and attention. Thus, reading is an excellent way of ensuring the brain is fit and healthy.

-
-

Stress Reduction

-
+
+

Stress Reduction

+

A well written novel or informative book can go a long way in making you forget about the worries of the world.

-
-

Increase in Knowledge

-
+
+

Increase in Knowledge

+

Reading will always fill your head with new information.

-
-

Entertainment

-
+
+

Entertainment

+

A plethora of genres can keep anyone entertained!

-
-

Better writing skills

-
+
+

Better writing skills

+

Being exposed to different writing styles allows you to be influenced to obtaining your own unique writing style.

diff --git a/output/blogs/2025/08/hilberts.hotel.html b/output/blogs/2025/08/hilberts.hotel.html index fc581c1..1f2d854 100644 --- a/output/blogs/2025/08/hilberts.hotel.html +++ b/output/blogs/2025/08/hilberts.hotel.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Hilbert's Hotel diff --git a/output/blogs/2025/08/spending-the-whole-day-on-this-website.html b/output/blogs/2025/08/spending-the-whole-day-on-this-website.html index f5f65f4..192a33a 100644 --- a/output/blogs/2025/08/spending-the-whole-day-on-this-website.html +++ b/output/blogs/2025/08/spending-the-whole-day-on-this-website.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + 09-08-2025: Website Changes @@ -220,9 +220,9 @@

09-08-2025: Website Changes

emacs website
-
-

What was worked on

-
+
+

What was worked on

+

I saw a few websites that used marginal notes on the right side of the screen like this one, so I decided to try and implement this feature in this wesbite. In my mind I thought of using an external pre-configured CSS that I can just insert and ta-da it would work.

diff --git a/output/blogs/2025/08/wacom-with-arch.html b/output/blogs/2025/08/wacom-with-arch.html index 9cfbddc..48774c9 100644 --- a/output/blogs/2025/08/wacom-with-arch.html +++ b/output/blogs/2025/08/wacom-with-arch.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Wacom With Arch @@ -220,9 +220,9 @@

Wacom With Arch

insights
-
-

Setting up Wacom Tablet in Arch Hyprland

-
+
+

Setting up Wacom Tablet in Arch Hyprland

+

I purchased a One by Wacom tablet almost 2 years ago now and it works flawlessly in both Windows and MacOS and even in most Linux distros with some configuration.

diff --git a/output/blogs/2025/08/weekly-review-week-ending-august-10-2025.html b/output/blogs/2025/08/weekly-review-week-ending-august-10-2025.html index 5a128a4..e1d945c 100644 --- a/output/blogs/2025/08/weekly-review-week-ending-august-10-2025.html +++ b/output/blogs/2025/08/weekly-review-week-ending-august-10-2025.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Weekly review: Week ending August 10, 2025 @@ -224,23 +224,23 @@

Table of Contents

-
-

Reviewing the week

-
+
+

Reviewing the week

+

Mostly continuing reading from the book clean code, also setup the ankii cards and this website. The amount of leetcode problems I solved could improve however.

@@ -254,27 +254,27 @@ I'm thinking of using time-blocks to represent the hours I spent doing each thin

-
-

Next week

-
+
+

Next week

+
-
-

DONE Read as much of Clean Code as possible

+
+

DONE Read as much of Clean Code as possible

-
-

TODO Finish another (misc) book

+
+

TODO Finish another (misc) book

-
-

DONE Write more (metric unspecified, need to experiment to see what works best)

+
+

DONE Write more (metric unspecified, need to experiment to see what works best)

-
-

TODO Start the book Dose Effect

+
+

TODO Start the book Dose Effect

-
-

DONE More leetcode problems to solve (again, metric unspecified)

+
+

DONE More leetcode problems to solve (again, metric unspecified)

-
-

TODO Touch typing: daily practice

+
+

TODO Touch typing: daily practice

diff --git a/output/blogs/2025/08/weekly-review-week-ending-august-17-2025.html b/output/blogs/2025/08/weekly-review-week-ending-august-17-2025.html index 954c805..e9f4bd9 100644 --- a/output/blogs/2025/08/weekly-review-week-ending-august-17-2025.html +++ b/output/blogs/2025/08/weekly-review-week-ending-august-17-2025.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Weekly review: Week ending August 17, 2025 @@ -224,65 +224,65 @@

Table of Contents

-
-

Previous Week

-
+
+

Previous Week

+
-
-

DONE Read as much of Clean Code as possible

+
+

DONE Read as much of Clean Code as possible

-
-

TODO Finish another (misc) book

+
+

TODO Finish another (misc) book

-
-

DONE Write more (metric unspecified, need to experiment to see what works best)

+
+

DONE Write more (metric unspecified, need to experiment to see what works best)

-
-

TODO Start the book Dose Effect

+
+

TODO Start the book Dose Effect

-
-

DONE More leetcode problems to solve (again, metric unspecified)

+
+

DONE More leetcode problems to solve (again, metric unspecified)

-
-

TODO Touch typing: daily practice

+
+

TODO Touch typing: daily practice

-
-

Next Week

-
+
+

Next Week

+
-
-

TODO 3/4 of Clean Code

+
+

TODO 3/4 of Clean Code

-
-

TODO More book notes

+
+

TODO More book notes

-
-

TODO Touch typing: daily practice

+
+

TODO Touch typing: daily practice

-
-

TODO Start the book Dose Effect

+
+

TODO Start the book Dose Effect

diff --git a/output/blogs/2025/08/weekly-review-week-ending-august-24-2025.html b/output/blogs/2025/08/weekly-review-week-ending-august-24-2025.html index 8dd1eea..2f2d905 100644 --- a/output/blogs/2025/08/weekly-review-week-ending-august-24-2025.html +++ b/output/blogs/2025/08/weekly-review-week-ending-august-24-2025.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Weekly review: Week ending August 24, 2025 @@ -224,11 +224,11 @@

Table of Contents

@@ -237,18 +237,18 @@

I seem to be spending less time working on technical crafts, primarily due to so many other commitments. Making it a goal to remove distractions and focus more on reading, writing and executing.

-
-

Next Week

-
+
+

Next Week

+
-
-

TODO Clean Code Finish

+
+

TODO Clean Code Finish

-
-

TODO Eliminate Distractions

+
+

TODO Eliminate Distractions

-
-

TODO Fix weekly schedule

+
+

TODO Fix weekly schedule

diff --git a/output/blogs/2025/08/what-do-i-want-to-do-with-emacs.html b/output/blogs/2025/08/what-do-i-want-to-do-with-emacs.html index b4228d3..e41b678 100644 --- a/output/blogs/2025/08/what-do-i-want-to-do-with-emacs.html +++ b/output/blogs/2025/08/what-do-i-want-to-do-with-emacs.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + What Do I Want To Do With Emacs @@ -245,7 +245,7 @@ After some thinking I narrowed it down and collated it in the following diagram:

-
+

2025-08-08-emacs.svg

diff --git a/output/blogs/2025/08/zettelkasten.html b/output/blogs/2025/08/zettelkasten.html index 8349097..bec6508 100644 --- a/output/blogs/2025/08/zettelkasten.html +++ b/output/blogs/2025/08/zettelkasten.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Zettelkasten Method @@ -220,9 +220,9 @@

Zettelkasten Method

education
-
-

The Zettelkasten Method

-
+
+

The Zettelkasten Method

+

This Zettelkasten method is growing in popularity for taking notes. Ever felt as though there's too much pieces of information but you don't know how to deal with it? This method solves exactly that problem and more. Think of it as forming a second brain, where you can jot down ideas and information whilst simultaneously being able to connect them together.

@@ -246,7 +246,7 @@ There are many personal knowledge management systems' (PKMS) out there that allo

-
+

org-roam-ui-graph.png

diff --git a/output/blogs/blogs-intro.html b/output/blogs/blogs-intro.html index 7ea4e31..38e95d0 100644 --- a/output/blogs/blogs-intro.html +++ b/output/blogs/blogs-intro.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Blogs Introduction @@ -220,9 +220,9 @@

Blogs Introduction

introduction
-
-

Introduction

-
+
+

Introduction

+

In this section you will find posts that are not as structured as the ones found in here. Mainly these will deal with findings, research, assorted writings and random bits and blobs.

diff --git a/output/blogs/blogs-list.html b/output/blogs/blogs-list.html index 83eb7ea..deae0f2 100644 --- a/output/blogs/blogs-list.html +++ b/output/blogs/blogs-list.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Blogs List @@ -214,16 +214,16 @@
-
Updated: 2025-08-27 Wed 22:32
+
Updated: 2025-08-28 Thu 17:03

Blogs List

See the categories: Categories

-
-

Blogs:

-
+
+

Blogs:

+
-
Updated: 2025-08-27 Wed 22:32
+
Updated: 2025-08-28 Thu 17:03
-
-

Categories (Includes both blogs and posts)

-
+
+

Categories (Includes both blogs and posts)

+

Contact

-
-

Contact Using the Following:

-
+
+

Contact Using the Following:

+

> LinkedIn: LinkedIn

diff --git a/output/index.html b/output/index.html index 3dc9e27..8811b55 100644 --- a/output/index.html +++ b/output/index.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Home Page @@ -221,15 +221,15 @@

Table of Contents

-
-

Welcome! 🌱

-
+
+

Welcome! 🌱

+

This is a website built using Emacs Org-mode and published using org-publish. The very first iteration of this website used the Angular framework, only after a while I realised (as every Emacs lover does) that I want to make this an Emacs-centric project

@@ -247,9 +247,9 @@ Feel free to explore:
-
-

How to publish web pages using org-publish

-
+
+

How to publish web pages using org-publish

+

This website is heavily inspired by some people who have decided to use org-publish as a way to convert org files into html. I came across a few that took the plunge and decided to migrate from platforms like Wordpress and instead opted for a more transparent, text-based workflow.

@@ -346,9 +346,9 @@ And there we go! The files are now being hosted on http://localhost:8000/<

-
-

Contact

-
+
+

Contact

+

Feel free to reach out on GitHub: https://github.com/zainezq

diff --git a/output/posts.html b/output/posts.html index 8bd6ff4..b8b8de5 100644 --- a/output/posts.html +++ b/output/posts.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Posts @@ -218,18 +218,18 @@

Posts

-
-

Links

-
+
+

Links

+
-
-

Posts Introduction   intro

+
+

Posts Introduction   intro

-
-

Zettelkasten Method   education

-
+
+

Zettelkasten Method   education

+

<2025-08-06 Wed>

diff --git a/output/posts/clean-code/clean-code-chapter-1.html b/output/posts/clean-code/clean-code-chapter-1.html index 0b4eabf..16e420c 100644 --- a/output/posts/clean-code/clean-code-chapter-1.html +++ b/output/posts/clean-code/clean-code-chapter-1.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Clean Code: Chapter 1 Notes @@ -224,16 +224,16 @@

Table of Contents

Link to Chapter 2

-
-

Chapter 1: Clean Code

-
+
+

Chapter 1: Clean Code

+

Referenced Items:

diff --git a/output/posts/clean-code/clean-code-chapter-2.html b/output/posts/clean-code/clean-code-chapter-2.html index 6433fa5..bd30845 100644 --- a/output/posts/clean-code/clean-code-chapter-2.html +++ b/output/posts/clean-code/clean-code-chapter-2.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Clean Code: Chapter 2 Notes @@ -214,7 +214,7 @@
-
Updated: 2025-08-12 Tue 18:29
+
Updated: 2025-08-28 Thu 16:52

Clean Code: Chapter 2 Notes

@@ -224,38 +224,37 @@

Table of Contents

-Link to Chapter 1 -Link to Chapter 3 +Link to Chapter 1 | Link to Chapter 3

-
-

Chapter 2: Meaningful Names

-
+
+

Chapter 2: Meaningful Names

+
-
-

Use intention revealing names:

-
+
+

Use intention revealing names:

+

Names should reveal intent, there is no revelation in naming an integer d, intending it stands for days. Instead, you should use the following names:

@@ -268,17 +267,17 @@ Names should reveal intent, there is no revelation in naming an integer d<
-
-

Avoid disinformation

-
+
+

Avoid disinformation

+

Don't postfix the word 'list' to the name 'accounts' unless it's actually a list. This is because the reader will assume the data type of accountsList is indeed a list, instead choose a name like accountsGroup.

-
-

Make Meaningful Distinctions

-
+
+

Make Meaningful Distinctions

+

While it is possible to name by being disinformative, it is also possible to name being non informative. Consider:

@@ -303,18 +302,18 @@ Furthermore, noise words are redundant. We should never use the word varia

-
-

Use Pronouncable Names

-
+
+

Use Pronouncable Names

+

This is quite straightforward. Do not use a name like genymdhms to refer to generation date, year, month, day, hour, minute, and second. Instead use generationTimeStamp.

-
-

Use Searchable Names

-
+
+

Use Searchable Names

+

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:

@@ -324,42 +323,42 @@ In modern IDE's, it is still quite difficult to search for single-lettered varia

-
-

Avoid Encodings

-
+
+

Avoid Encodings

+

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: PhoneNumber phoneString; we can see the reader being misled into thinking the phone number is a String.

-
-

Avoid Mental Mappings

-
+
+

Avoid Mental Mappings

+

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.

-
-

Class Names

-
+
+

Class Names

+

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

-
-

Method Names

-
+
+

Method Names

+

Methods should have verb or verb phrase names.

-
-

Don't be cute/Don't use puns

-
+
+

Don't be cute/Don't use puns

+

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.

@@ -369,17 +368,17 @@ Do not use names that are only understandable to people whom you share jokes etc
-
-

Pick one word per concept

-
+
+

Pick one word per concept

+

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.

-
-

Solution Domain Names and Problem Domain Names

-
+
+

Solution Domain Names and Problem Domain Names

+

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.

@@ -389,17 +388,17 @@ However when it is not possible to use solution domain names (in other words, wh

-
-

Add Meaningful Context

-
+
+

Add Meaningful Context

+

Enclose names with well-named classes, functions, or namespaces. When all else fails, then prefix with something that provides more context.

-
-

Don't add gratuitous context

-
+
+

Don't add gratuitous context

+

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'.

diff --git a/output/posts/clean-code/clean-code-chapter-3.html b/output/posts/clean-code/clean-code-chapter-3.html index 2ba5670..91c25b3 100644 --- a/output/posts/clean-code/clean-code-chapter-3.html +++ b/output/posts/clean-code/clean-code-chapter-3.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Clean Code: Chapter 3 Notes @@ -214,7 +214,7 @@
-
Updated: 2025-08-12 Tue 18:30
+
Updated: 2025-08-28 Thu 16:52

Clean Code: Chapter 3 Notes

@@ -224,30 +224,30 @@

Table of Contents

-Link to Chapter 2 +Link to Chapter 2 | Link to Chapter 4

-
-

Chapter 3: Functions

-
+
+

Chapter 3: Functions

+
-
-

Functions should be small

-
+
+

Functions should be small

+

Functions should be extremely short—ideally just a few lines, so they remain easy to understand and maintain.

@@ -269,9 +269,9 @@ Large functions hide complexity and mix abstraction levels, making errors and du

-
-

Do One Thing & One Level of Abstraction

-
+
+

Do One Thing & One Level of Abstraction

+

A function should do exactly one conceptual task, and all its statements should exist at the same abstraction level.

@@ -293,9 +293,9 @@ Functions that “do one thing” cannot be logically split into sections such a

-
-

Switch Statements

-
+
+

Switch Statements

+

Switch statements naturally violate “do one thing” by handling multiple cases; they also grow in size over time.

@@ -350,9 +350,9 @@ Example:
-
-

Use Descriptive Names

-
+
+

Use Descriptive Names

+

A function’s name should clearly state its purpose. Long, descriptive names beat short, cryptic ones.

@@ -374,9 +374,9 @@ IDE refactoring tools make renaming safe, encouraging experimentation.

-
-

Function Arguments

-
+
+

Function Arguments

+

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.

@@ -402,9 +402,9 @@ Match function/argument names in verb–noun or keyword style (e.g., write

-
-

Have No Side Effects

-
+
+

Have No Side Effects

+

A function should do only what its name promises. Hidden state changes are misleading and dangerous.

@@ -426,9 +426,9 @@ Functions that modify state and return information often cause confusion and sho

-
-

Error Handling

-
+
+

Error Handling

+

Error handling is a single responsibility—separate it from normal logic to keep both paths clear.

diff --git a/output/posts/clean-code/clean-code-chapter-4.html b/output/posts/clean-code/clean-code-chapter-4.html new file mode 100644 index 0000000..a4a21e5 --- /dev/null +++ b/output/posts/clean-code/clean-code-chapter-4.html @@ -0,0 +1,618 @@ + + + + + + + +Clean Code: Chapter 4 Notes + + + + + + + + + + + + +
+ + +
Updated: 2025-08-28 Thu 16:52
+
+
+

Clean Code: Chapter 4 Notes

+
books notes
+ + +

+Link to Chapter 3 | Link to Chapter 5 +

+
+

Chapter 4: Comments

+
+

+Comments are a necessary evil—they exist because code fails to express intent clearly. +

+ +

+Outdated comments are dangerous; they can mislead more than help. +

+ +

+Strive to write code that explains itself; comments should be minimised. +

+ +

+Truth is always in the code, not in the comments. +

+
+
+

Comments Do Not Make Up for Bad Code

+
+

+Don’t use comments to excuse messy, unclear code. Clean the code instead. +

+ +

+Clear, expressive code with few comments > cluttered code with many comments. +

+ +
+
+// Check to see if the employee is eligible for full benefits
+if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
+
+// Better:
+if (employee.isEligibleForFullBenefits())
+
+
+
+
+
+
+

Good Comments

+
+

+Only write them when unavoidable. Such as in the following instances: +

+
+
+

Legal Comments

+
+

+Sometimes required for copyright/licensing. +

+ +

+Keep them short; refer to standard licenses rather than embedding full legal text. +

+
+
+
+

Informative Comments

+
+

+Explain return values, formats, or patterns. +

+ +

+Prefer naming/structuring code to make such comments unnecessary. +

+ +
+
+// format matched kk:mm:ss EEE, MMM dd, yyyy
+Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
+
+
+
+
+
+
+

Explanation of Intent

+
+

+Describe why a certain approach was chosen. +

+ +

+Helps future maintainers understand reasoning behind code. +

+ +
+
+public int compareTo(Object o)
+{
+    if(o instanceof WikiPagePath)
+        { WikiPagePath p = (WikiPagePath) o;
+            String compressedName = StringUtil.join(names, "");
+            String compressedArgumentName = StringUtil.join(p.names, "");
+            return compressedName.compareTo(compressedArgumentName);
+        }
+    return 1; // we are greater because we are the right type.
+}
+
+
+
+
+
+
+

Clarification

+
+

+Translate obscure values into readable terms. +

+ +

+Useful when working with unchangeable APIs/libraries, but risky if incorrect. +

+
+
+
+

Warning of Consequences

+
+

+Alert others about performance, thread-safety, or side effects. +

+ +

+For example, in code you can say: +

+ +

+// SimpleDateFormat is not thread safe, so create each instance independently. +

+
+
+
+

TODO Comments

+
+

+Mark incomplete work or planned improvements. +

+ +

+Should be reviewed regularly; not an excuse for bad code. +

+
+
+
+

Amplification

+
+

+Highlight the importance of seemingly small details. +

+ +

+// the trim is real important. It removes starting spaces... +

+
+
+
+

Javadocs in Public APIs

+
+

+Public APIs should have clear documentation. +

+ +

+Javadocs can also mislead. Keep them accurate and up-to-date. +

+
+
+
+
+

Bad Comments

+
+
    +
  • Don't place a comment just because you feel like it.
    • +
  • Remove redundant comments.
    • +
  • Avoid misleading comments.
    • +
  • Don't mandate everything (not every function needs a Javadoc).
    • +
  • No need for journal comments, we have source control.
    • +
  • Remove noise comments.
    • +
+
+
+

Don’t Use a Comment When You Can Use a Function or Variable

+
+

+Replace explanatory comments with expressive variable or function names. +

+ +

+Refactor code to remove comment redundancy. +

+
+
+
+

Position Markers

+
+

+Avoid decorative banners like // Actions ///////////////////////, they add clutter. +

+ +

+Use sparingly and only for meaningful grouping. +

+ +

+Overuse makes them blend into background noise. +

+
+
+
+

Closing Brace Comments

+
+

+Comments on closing braces (} // while) are unnecessary for small, well structured functions. +

+ +

+Prefer short, clear functions over brace markers. +

+
+
+
+

Attributions and Bylines

+
+

+Don’t add personal tags like /* Added by Rick */, use version control for authorship history. +

+ +

+Such comments become outdated and irrelevant over time. +

+
+
+
+

Commented Out Code

+
+

+Never keep old code commented out; delete it and rely on version control history. +

+ +

+Commented-out code adds clutter and confuses future maintainers. +

+ +
+
+// Old cruft that should be deleted:
+//hdrPos = bytePos;
+//dataPos = bytePos;
+
+
+
+
+
+
+

HTML Comments

+
+

+Avoid HTML markup inside code comments, it makes them harder to read in the editor. +

+ +

+Let documentation tools (like Javadoc) handle formatting. +

+
+
+
+

Nonlocal Information

+
+

+Comments should describe nearby code only, not unrelated parts of the system. +

+ +

+Avoid embedding global/system details that the function can’t control. +

+
+
+
+

Too Much Information

+
+

+Avoid long, unnecessary historical or technical explanations. +

+ +

+Keep only relevant context (e.g., “RFC 2045” reference is fine, not the full spec). +

+
+
+
+

Inobvious Connection

+
+

+Ensure the relationship between comment and code is clear. +

+ +

+Don’t make readers guess what part of the code the comment refers to. +

+ +
+
+// plus filter bytes ... but which part is “filter”?
+this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];
+
+
+
+
+
+
+

Function Headers

+
+

+Short, single purpose functions with good names don’t need header comments. +

+ +

+Let the function name explain the purpose. +

+
+
+
+

Javadocs in Nonpublic Code

+
+

+Javadocs are useful for public APIs, but excessive formality in internal code is just noise. +

+ +

+Internal methods should be self explanatory without full doc comments. +

+
+
+
+
+
+
+
+
+
+Copyright © 2022-2025 Zaine Qayyum. All rights reserved unless otherwise noted.
+
+Created with Emacs 30.1 (Org mode 9.7.11) on Arch GNU/Linux +
+
+
+ + diff --git a/output/posts/clean-code/clean-code-chapter-5.html b/output/posts/clean-code/clean-code-chapter-5.html new file mode 100644 index 0000000..171c746 --- /dev/null +++ b/output/posts/clean-code/clean-code-chapter-5.html @@ -0,0 +1,560 @@ + + + + + + + +Clean Code: Chapter 5 Notes + + + + + + + + + + + + +
+ + +
Updated: 2025-08-28 Thu 17:03
+
+
+

Clean Code: Chapter 5 Notes

+
books notes
+ + +

+Link to Chapter 4 | Link to Chapter 6 +

+
+

Chapter 5: Formatting

+
+
+
+

Vertical Formatting

+
+
    +
  • Vertical openness (blank lines) separates concepts and improves readability.
    • +
  • Too much density makes code look like a muddle and harder to scan.
    • +
+
+
+

Vertical Density

+
+
    +
  • Tightly related lines should appear vertically dense.
    • +
  • Avoid useless comments that interrupt association.
    • +
  • Example (bad):
    • +
+
+
public class ReporterConfig {
+/**
+* The class name of the reporter listener
+*/
+private String m_className;
+
+
+ +
    +
  • Example (better):
    • +
+
+
public class ReporterConfig {
+private String m_className;
+private List<Property> m_properties = new ArrayList<>();
+
+
+
+
+
+

Vertical Distance

+
+
    +
  • Related concepts should be kept close together to reduce scrolling and searching.
    • +
  • Local variables → as close to use as possible, usually at top of function.
    • +
  • Control variables → declared inside loop headers.
    • +
  • Instance variables → declared at the top of class (common Java convention).
    • +
+ +
+
for (Test each : tests) {
+    count += each.countTestCases();
+}
+
+
+ +
    +
  • Dependent functions: caller above callee for natural top-down reading.
    • +
+
+
public Response makeResponse(...) {
+    String pageName = getPageNameOrDefault(request, "FrontPage");
+    loadPage(pageName, context);
+    return makePageResponse(context);
+}
+
+private String getPageNameOrDefault(Request request, String defaultPageName) { ... }
+
+
+
+
+
+

Conceptual Affinity

+
+
    +
  • Group functions with similar naming or shared purpose.
    • +
  • Example (JUnit assert methods):
    • +
+
+
static public void assertTrue(String message, boolean condition) { ... }
+static public void assertTrue(boolean condition) { ... }
+static public void assertFalse(String message, boolean condition) { ... }
+static public void assertFalse(boolean condition) { ... }
+
+
+
+
+
+

Vertical Ordering

+
+
    +
  • Organise code top down: +
      +
    • High-level concepts first (main logic).
      • +
    • Lower-level details later.
      • +
    • +
  • Readers can skim like a newspaper: important first, details last.
    • +
  • Contrast: C/C++ require declarations before use, Java does not.
    • +
+
+
+
+

Summary - vertical

+
+
    +
  • Use vertical openness to separate concepts.
    • +
  • Use vertical density to group related ones.
    • +
  • Keep related variables, methods, and concepts close together.
    • +
  • Order code top down for natural readability.
    • +
+
+
+
+
+

Horizontal Formatting

+
+

+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. +

+ +

+Avoid shrinking font or overly wide monitors to fit more code, readability > fitting more characters. +

+ +

+Example limit guideline: +

+ +
+
// Good (short)
+int sum = a + b + c;
+
+// Bad (too long)
+int sum = a + b + c + d + e + f + g + h + i + j + k + l + m + n + o + p + q;
+
+
+
+
+

Horizontal Openness and Density

+
+

+Use spaces to separate low-precedence operators (e.g., +, -, =) and improve readability. +

+ +

+Do not put spaces between function names and parentheses, they are closely related. +

+ +

+Example (Quadratic formula formatting): +

+ +
+
return (-b + Math.sqrt(determinant)) / (2*a);
+
+
+ +

+Separate arguments with spaces after commas to show distinct parameters. +

+
+
+
+

Horizontal Alignment

+
+

+Avoid aligning variable declarations or assignments in columns, it draws the eye to the wrong place. +

+ +

+Long aligned lists usually mean the class is too large and should be split. +

+ +

+Example (preferred unaligned): +

+ +
+
// Prefer this:
+private Socket socket;
+private InputStream input;
+private OutputStream output;
+
+//instead of:
+private Socket       socket;
+private InputStream  input;
+private OutputStream output;
+
+
+
+
+
+
+

Indentation

+
+

+Indent according to scope hierarchy: +

+ +

+Classes → no indent +

+ +

+Methods → 1 level +

+ +

+Method bodies → 2 levels +

+ +

+Inner blocks → +1 for each nesting +

+ +

+Indentation makes scopes visually obvious; without it, code is hard to scan. +

+ +

+Avoid collapsing scopes onto one line, always use braces and proper indenting. +

+
+
+
+

Dummy Scopes

+
+

+Avoid dummy bodies in loops (e.g., empty while or for loops). +

+ +

+If unavoidable, place semicolon on its own indented line to make it visible. +

+ +
+
while (dis.read(buf, 0, size) != -1)
+    ;
+
+
+
+
+
+
+

Team Rules

+
+

+Teams must agree on a single formatting style for consistency. +

+ +

+Use IDE formatters to enforce these rules across all files. +

+ +

+Consistent formatting builds trust and reduces mental load for readers. +

+
+
+
+

Uncle Bob’s Formatting Rules (Example in CodeAnalyzer.java)

+
+

+Short, clear methods with consistent spacing and indentation. +

+ +

+Use spaces around assignment and low-precedence operators, no space for high precedence operators. +

+ +

+Avoid deeply nested structures. Prefer clear, flat logic. +

+ +

+Example snippet: +

+ +
+
private void measureLine(String line) {
+  lineCount++;
+  int lineSize = line.length();
+  totalChars += lineSize;
+  lineWidthHistogram.addLine(lineSize, lineCount);
+  recordWidestLine(lineSize);
+}
+
+
+
+
+
+
+
+
+
+
+Copyright © 2022-2025 Zaine Qayyum. All rights reserved unless otherwise noted.
+
+Created with Emacs 30.1 (Org mode 9.7.11) on Arch GNU/Linux +
+
+
+ + diff --git a/output/posts/posts-intro.html b/output/posts/posts-intro.html index 0684858..cba672e 100644 --- a/output/posts/posts-intro.html +++ b/output/posts/posts-intro.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Posts Introduction @@ -220,9 +220,9 @@

Posts Introduction

introduction
-
-

Introduction

-
+
+

Introduction

+

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 posts is to develop the skill of being able to deliver habitual high quality explanations as well as reinforcing the topic(s) learnt.

diff --git a/output/posts/posts-list.html b/output/posts/posts-list.html index 5889ede..0bea886 100644 --- a/output/posts/posts-list.html +++ b/output/posts/posts-list.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Posts List @@ -214,17 +214,19 @@
-
Updated: 2025-08-27 Wed 22:32
+
Updated: 2025-08-28 Thu 17:03

Posts List

See the categories: Categories

-
-

Posts:

-
+
+

Posts:

+

Setup

-
-

Introduction

-
+
+

Introduction

+

Last updated: <2025-08-10 Sun 20:42>

@@ -235,9 +235,9 @@ This page will highlight the build-script.el used to generate this
-
-

The script

-
+
+

The script

+

The script is as follows, at the start I have some metadata relating to the file, followed by package management,then the declaration of variables/functions and finally the org-publish-project-alist which handles nearly all of the project generation instructions.

@@ -650,9 +650,9 @@ Created with %c on <a href=\"https://www.archlinux.org/\">Arch</a> &
-
-

Publish Script

-
+
+

Publish Script

+

As the project is hosted on Github, I have created a small script that is able to push changes to the remote repository, which Cloudflare will automatically detect and rebuild the website:

diff --git a/output/sitemap.html b/output/sitemap.html index 7f53429..5edffd0 100644 --- a/output/sitemap.html +++ b/output/sitemap.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Sitemap @@ -214,7 +214,7 @@
-
Updated: 2025-08-27 Wed 22:32
+
Updated: 2025-08-28 Thu 17:03

Sitemap

@@ -234,6 +234,8 @@
  • Clean Code: Chapter 1 Notes
  • Clean Code: Chapter 2 Notes
  • Clean Code: Chapter 3 Notes
    • +
  • Clean Code: Chapter 4 Notes
    • +
  • Clean Code: Chapter 5 Notes
  • blogs @@ -245,14 +247,14 @@
    • diff --git a/output/tags/books.html b/output/tags/books.html index 4822d3c..80025fb 100644 --- a/output/tags/books.html +++ b/output/tags/books.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: books @@ -214,13 +214,15 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged books

    -
    +
    +

    Posts tagged books

    +
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged education

    -
    +
    +

    Posts tagged education

    +
    diff --git a/output/tags/emacs.html b/output/tags/emacs.html index 9113794..be6914b 100644 --- a/output/tags/emacs.html +++ b/output/tags/emacs.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: emacs @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged emacs

    -
    +
    +

    Posts tagged emacs

    +
    • 09-08-2025: Website Changes
    • What Do I Want To Do With Emacs
      • diff --git a/output/tags/insights.html b/output/tags/insights.html index d8a4151..b2cc748 100644 --- a/output/tags/insights.html +++ b/output/tags/insights.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: insights @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged insights

    -
    +
    +

    Posts tagged insights

    +
    • Benefits of Reading
    • Hilbert's Hotel
      • diff --git a/output/tags/introduction.html b/output/tags/introduction.html index c2ee45f..b7bd947 100644 --- a/output/tags/introduction.html +++ b/output/tags/introduction.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: introduction @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged introduction

    -
    +
    +

    Posts tagged introduction

    +
    • Blogs Introduction
    • Posts Introduction
      • diff --git a/output/tags/maths.html b/output/tags/maths.html index 7613cf4..ec390ed 100644 --- a/output/tags/maths.html +++ b/output/tags/maths.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: maths @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged maths

    -
    +
    +

    Posts tagged maths

    +
    diff --git a/output/tags/notes.html b/output/tags/notes.html index 3643bc2..8b8d2f5 100644 --- a/output/tags/notes.html +++ b/output/tags/notes.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: notes @@ -214,13 +214,15 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged notes

    -
    +
    +

    Posts tagged notes

    +
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged reading

    -
    +
    +

    Posts tagged reading

    +
    diff --git a/output/tags/review.html b/output/tags/review.html index e09cba3..d2975df 100644 --- a/output/tags/review.html +++ b/output/tags/review.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: review @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged review

    -
    +
    +

    Posts tagged review

    +
    diff --git a/output/tags/website.html b/output/tags/website.html index d10ce45..4c2a3c8 100644 --- a/output/tags/website.html +++ b/output/tags/website.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: website @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged website

    -
    +
    +

    Posts tagged website

    +
    diff --git a/output/tags/weekly-review.html b/output/tags/weekly-review.html index 22390f5..5b916f5 100644 --- a/output/tags/weekly-review.html +++ b/output/tags/weekly-review.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Tag: weekly-review @@ -214,12 +214,12 @@
    -
    Updated: 2025-08-27 Wed 22:32
    +
    Updated: 2025-08-28 Thu 17:03
    -
    -

    Posts tagged weekly-review

    -
    +