422 lines
17 KiB
HTML
422 lines
17 KiB
HTML
<?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-27 Wed 21:14 -->
|
|
<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>
|
|
<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-12 Tue 18:29</div>
|
|
</div>
|
|
<div id="content" class="content">
|
|
<h1 class="title">Clean Code: Chapter 2 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="#org581bdc3">Chapter 2: Meaningful Names</a>
|
|
<ul>
|
|
<li><a href="#orgc763196">Use intention revealing names:</a></li>
|
|
<li><a href="#orgdecf450">Avoid disinformation</a></li>
|
|
<li><a href="#org8474847">Make Meaningful Distinctions</a></li>
|
|
<li><a href="#orgbbbe06c">Use Pronouncable Names</a></li>
|
|
<li><a href="#org3f0a8e5">Use Searchable Names</a></li>
|
|
<li><a href="#orgc12ee54">Avoid Encodings</a></li>
|
|
<li><a href="#org90ee7a9">Avoid Mental Mappings</a></li>
|
|
<li><a href="#orga124cfc">Class Names</a></li>
|
|
<li><a href="#orgf988299">Method Names</a></li>
|
|
<li><a href="#org12bfea9">Don't be cute/Don't use puns</a></li>
|
|
<li><a href="#orga33a68e">Pick one word per concept</a></li>
|
|
<li><a href="#org6fddbc9">Solution Domain Names and Problem Domain Names</a></li>
|
|
<li><a href="#orge603c17">Add Meaningful Context</a></li>
|
|
<li><a href="#org2fc0448">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>
|
|
</p>
|
|
<div id="outline-container-org581bdc3" class="outline-2">
|
|
<h2 id="org581bdc3">Chapter 2: Meaningful Names</h2>
|
|
<div class="outline-text-2" id="text-org581bdc3">
|
|
</div>
|
|
<div id="outline-container-orgc763196" class="outline-3">
|
|
<h3 id="orgc763196">Use intention revealing names:</h3>
|
|
<div class="outline-text-3" id="text-orgc763196">
|
|
<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>
|
|
<div class="org-src-container">
|
|
<pre class="src src-java"><span class="org-type">int</span> <span class="org-variable-name">elapsedTimeInDays</span>;
|
|
<span class="org-type">int</span> <span class="org-variable-name">daysSinceCreation</span>;
|
|
<span class="org-type">int</span> <span class="org-variable-name">daysSinceModification</span>;
|
|
<span class="org-type">int</span> <span class="org-variable-name">fileAgeInDays</span>;
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-orgdecf450" class="outline-3">
|
|
<h3 id="orgdecf450">Avoid disinformation</h3>
|
|
<div class="outline-text-3" id="text-orgdecf450">
|
|
<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-org8474847" class="outline-3">
|
|
<h3 id="org8474847">Make Meaningful Distinctions</h3>
|
|
<div class="outline-text-3" id="text-org8474847">
|
|
<p>
|
|
While it is possible to name by being disinformative, it is also possible to name being non informative. Consider:
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-java">
|
|
<span class="org-keyword">public</span> <span class="org-keyword">static</span> <span class="org-type">void</span> <span class="org-function-name">copyChars</span>(<span class="org-type">char</span> <span class="org-variable-name">a1</span>[], <span class="org-type">char</span> <span class="org-variable-name">a2</span>[]) {
|
|
<span class="org-keyword">for</span> (<span class="org-type">int</span> <span class="org-variable-name">i</span> = 0; i < a1.length; i++) {
|
|
a2[i] = a1[i];
|
|
}
|
|
}
|
|
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
What on earth does <code>a[1]</code> and <code>a[2]</code> even stand for? We are better off using names like source and destination (due to the function's intent of copying the array).
|
|
</p>
|
|
|
|
<p>
|
|
Furthermore, noise words are redundant. We should never use the word <code>variable</code> when naming a variable, or <code>table</code> when naming a table.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-orgbbbe06c" class="outline-3">
|
|
<h3 id="orgbbbe06c">Use Pronouncable Names</h3>
|
|
<div class="outline-text-3" id="text-orgbbbe06c">
|
|
<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-org3f0a8e5" class="outline-3">
|
|
<h3 id="org3f0a8e5">Use Searchable Names</h3>
|
|
<div class="outline-text-3" id="text-org3f0a8e5">
|
|
<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>
|
|
|
|
<p>
|
|
<i>The length of a name should correspond to the size of its scope</i>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-orgc12ee54" class="outline-3">
|
|
<h3 id="orgc12ee54">Avoid Encodings</h3>
|
|
<div class="outline-text-3" id="text-orgc12ee54">
|
|
<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-org90ee7a9" class="outline-3">
|
|
<h3 id="org90ee7a9">Avoid Mental Mappings</h3>
|
|
<div class="outline-text-3" id="text-org90ee7a9">
|
|
<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-orga124cfc" class="outline-3">
|
|
<h3 id="orga124cfc">Class Names</h3>
|
|
<div class="outline-text-3" id="text-orga124cfc">
|
|
<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-orgf988299" class="outline-3">
|
|
<h3 id="orgf988299">Method Names</h3>
|
|
<div class="outline-text-3" id="text-orgf988299">
|
|
<p>
|
|
Methods should have verb or verb phrase names.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-org12bfea9" class="outline-3">
|
|
<h3 id="org12bfea9">Don't be cute/Don't use puns</h3>
|
|
<div class="outline-text-3" id="text-org12bfea9">
|
|
<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>
|
|
<ul class="org-ul">
|
|
<li>Example: <code>HandGrenade</code> instead of <code>DeleteItems</code></li>
|
|
<li>Example: <code>whack()</code> instead of <code>kill()</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-orga33a68e" class="outline-3">
|
|
<h3 id="orga33a68e">Pick one word per concept</h3>
|
|
<div class="outline-text-3" id="text-orga33a68e">
|
|
<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-org6fddbc9" class="outline-3">
|
|
<h3 id="org6fddbc9">Solution Domain Names and Problem Domain Names</h3>
|
|
<div class="outline-text-3" id="text-org6fddbc9">
|
|
<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>
|
|
|
|
<p>
|
|
However when it is not possible to use solution domain names (in other words, when there is no "programmer-eese" then use the name from the problem domain. The other programmers can ask the domain expert for clarification. If the code is more to do with the problem domain concepts, then the names should be drawn from them.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-orge603c17" class="outline-3">
|
|
<h3 id="orge603c17">Add Meaningful Context</h3>
|
|
<div class="outline-text-3" id="text-orge603c17">
|
|
<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-org2fc0448" class="outline-3">
|
|
<h3 id="org2fc0448">Don't add gratuitous context</h3>
|
|
<div class="outline-text-3" id="text-org2fc0448">
|
|
<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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="postamble" class="status">
|
|
<footer>
|
|
<div class="copyright-container">
|
|
<div class="copyright">
|
|
Copyright © 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>
|