Aarni Pesonen
Clean Coding
Metropolia University of Applied Sciences
English Report
17 November 2020
*Table of Contents* Paragrapheille nimet?
*List of abbreviations*
Test Driven Development (TDD) ei mainintaa tekstissä?
Engine Control Unit (ECU)
Variable
Function
Debugging
Object-oriented programming - OOP
Beginners' All-purpose Symbolic Instruction Code (BASIC) ei tule lopulliseen tekstiin
(Introduction, general background info, mention and define topic + goal)
In today’s world, code can be found everywhere (from watches to home appliances, cars to
smart phones. A modern smart phone has more computing power available than all existing
computers in the 80’s combined [Robert C. Martin, youtube lecture]. All these smart devices
require lines of code to function. This raises the questions: who or what produces the code?
Code is created by human beings or in some cases computers, that have been programmed to
do so by humans. Is all code then created equal? According to Robert “Uncle Bob” Martin
(2009: 7), there are as many approaches to creating code as there are programmers. In other
words, there are countless different ways to code a function, that in the end performs the same
exact task. In almost all cases the “form” of the code is “invisible” to the end user. (A driver
depresses the accelerator pedal of a car and witnesses a corresponding speed increase. The
driver in question, most likely has no idea what sort of code and functions are run in the ECU
(engine control unit) of a car?.
With the end user being oblivious to inner workings of the software, it is up to the software
engineer to produce code that performs the function it is supposed to. Are there any additional
requirements for professional code, besides the software performing the intended task? The
industry experts seem to think so.
Development principles recommended and followed by hardened industry veterans form the
basis of the clean code movement. These principles offer guidelines and conventions for
software developers to follow, so that potential common pit falls and later stage complications
could be minimized.
*What is clean code? Does clean code matter? How is clean code produced? Is there a universal
consensus of what clean code is?*
The aim of this report is to explore various definitions of clean code, and explain why coding
clean should be the goal of every software engineer.
Defining a seemingly abstract concept such as clean code is not straightforward. However,
studying the approaches of industry veterans reveals some underlying core principles that
succesful developers vehemently follow. Few of these principles will be discussed next from
perspective of industry experts.
Bjarne Stroustrup, the inventor of C++ programming language, prefers efficient and elegant
code with straightforward logic (Martin, 2009: 7). Minimizing the amount of dependencies
provides improved maintainability. Care must be taken when performing code optimization not
to sacrifice readability (ibid.).
Emphasized here are the simplicity and transparency of the code. Bjarne also implies that
fixating on just pure performance optimization may hinder ability to decipher? the code.
Grady Booch, author of Design with Applications and Object Oriented Analysis, says plain and to
the point code, equivalent to well-written literature, is clean code. Intention of the designer
should not be masked by long lines of syntax and multitude of distended functions, but instead
giving the control to the programmer in a straightforward manner. (Martin 2009: 8)
Dave Thomas, founder of OTI (Object Technology International), godfather of Eclipse strategy
thinks interpretation and augmenting software should be just as easily accomplished by other
developers as the original author. This requires paying close attention to naming conventions of
variables, classes and entities. Programs should only have functions that perform a single task,
designed in a way where individual tasks can only be performed by a single function.
Accomplishing the above requires eliminating unnecessary dependencies, along with making
the code literate to clearly express intention. (Martin 2009: 9)
Ron Jeffries, the author of Extreme Programming Adventures in C# and Extreme Programming
Installed, notes clean code should always pass appropriate tests. If there is a problem, it should
be dealt with on the spot, rather than left for the future maintainer to cope with. Identical
duplicate lines of code are seen as redundant and should be avoided. In addition, the design
principles of the system should be clearly distinguishable from the code alone. Minimizing the
number of classes and functions will help keep the code base compact. (Martin 2009: 10)
It is apparent that the definition of clean code varies from person to person. There are however
fundamental principle overlap between opinions expressed by the experts of the field.
Simplicity, readability, straightforward functions, clear entity naming, along with low
dependency factor are the most heralded principles. Countless hours of practice, work and
execution develop not only skill, but individual preferences.
Figure 1: "Code A"
Figure 1: "Code B"
Demonstrated in figure 1 and figure 2 is the effect of naming and indentation practices. When
run, Code A and Code B perform identical to each other. From Code B, however it more
convenient to identify the intended function of this simple program. With increased number of
code lines and functions, this effect multiplies exponentially.
Entity names Clean Code p 309
What makes software readable are the names of entities such as variables, functions and
classes, the building blocks of programs (Martin, 2009: 309). These blocks can be found from all
code, regardless of what language it has been written in, with the exception of classes that are
only present in object-oriented programming or OOP*.
Names should accurately describe the use of a function, role of a variable or a class at the
appropriate abstraction level, so great care should be exercised when choosing them. The
entity names should be routinely evaluated during code maintenance. (Martin, 2009:311)
Adding additional descriptions alongside the code to help describe program function is a
debated subject among software developers. This type of additional description is called
commenting. It is the act of inserting lines amidst the code, marked by special signs that signify
the complier not to interpret these lines.
In the early days of programming - because of hardware memory constraints - it was common
for the variables to have hard-coded size/character limits for their reserved names. Because of
this, developers were encouraged to add comments to their coded work to explain the
programs function further(Martin, Youtubevideo). Modern programming languages do not
force such constraints and therefore expressive naming is no longer limited by finite character
count.
To this day?, programmers in training are encouraged to deliberately practice commenting to
aid in code comprehensions, when knowledge of the syntax has not yet been ingrained in the
mind?. This practice also makes sense, as returning to a project after weeks, months or years
often means having to “relearn” the quirks of the code in question?.
By professional standards, comments exemplify failure to express intent and function with the
code itself and should only be used as a last resort. Instead of resorting to commenting, the
developer should strive to make the code itself as descriptive as possible (Martin, 2009: 55).
Code should be clear and simple enough to not require additional commenting. (Martin, 2009:
55 = comments)? Martin, 2009:286 = comments)
Comment lines inserted between the actual program code do interrupt the flow to a degree,
therefore reducing initial readability. Usefulness of commenting does increase when multiple
developers of varying skill levels are expected to work on the same code base. Junior
developers are more likely to benefit from well-placed descriptions of functions. Necessity of
comments should be evaluated on a case-by-case basis. It can also be argued that their upkeep
adds to the already laborious task of code maintenance[?].
*
Why is clean coding important? From the perspective of a company as a client, programmer or
end-customer, multiple benefits can be found supporting the idea that code should be made
clean*. Whether the code in question is self-produced or authored by a third party, maintaining
and working with “messy” code takes time. It is not uncommon to see productivity drop by a
factor of ten or more [RCMYTlecture]. When a function is coded dependent of one or more
other functions, required effort for maintenance multiplies, consuming *man-hours in the
process.*
Debugging & Maintenance
Potentially huge monetary savings can be made when quality of the produced software is high.
(huono topic sentence?)
In the event of an error, unexpected program behavior, or a crash, the cause must be
identified. This procedure is called debugging. Depending on the size of the program, and
elusiveness of the cause - often called a bug - difficulty of the task varies. Debugging, along with
code base maintenance are the two most time-consuming phases of development (Martin,
2009:69). Cleanliness of the code has a direct correlation to debugging and maintenance times.
Software development should be likened to an endurance event rather than a speed race,
where the only way to win is with consistency (Martin, 2011: 69).
From the perspective of efficiency and speed, going slower in the beginning by coding clean,
the benefits can be reaped whenever debugging or maintenance work is done.*
Safety concerns
Even more important than monetary reasons are matters of safety. Devices, of which safety
features are electronically operated require code to perform their function. Modern vehicles
are an example of a product, which systems are almost entirely controlled by electronics. A
standard modern car has over one hundred million lines of code embedded in its systems
(Martin, 2019: p?).
When dealing with software that human life depends on, the developer is ultimately
responsible for the produced code (Martin, 2019: p?). In order to carry out efficient software
updates and ensure maximum safety within systems, code optimization is paramount.
How to produce clean code? Add Refactoring info!
How is clean code produced? Developer benefits from a fresh state of mind, as coding is a
intellectually challenging activity, where multiple factors have to be taken into consideration
simultaneously (Martin, 2011:58). In addition to being expressive, the actual software needs to
solve customer’s problem, while being able to integrate within existing systems. (Martin
2009:59)
Because of how the human mind works, clean code is not produced by default (Martin
Youtubevideo). First step is to make the code functional (Martin, 2009:268). However, a
program is not considered finished when the initial coding of its functions are done and
software is able to run (Martin Youtube). The state of the code rarely if ever is in the condition
suitable for handing it in as a finished product.* This is where refactoring comes into play. After
a program performs as intended, the code should be refactored, or “cleaned”. Creating
abstraction from repetitive code or straight duplication, revising functions are all an integral
part of the refactoring process (Martin 2009:289, infoa useammalla sivulla). Refactoring is in
many ways comparable to editing initial text after rough ideas have been put down on the
paper. The end result should be simple, transparent code with functions that only perform one
task each. No duplication or unnecessary dependencies. Easy to read, interpret and maintain by
someone other than original author(?).
(Conclusion)
By now it should be clear that absolute definition for clean code does not exist. In the end it
comes down to adhering to the underlying principles and constantly revisioning/refactoring to
maintain “cleanliness” of code. Individual preferences will wary, but following tried and true
design guidelines results equally functional, optimized code.
Non-refactored code ends up more costly in the long run, and the escalating effect of poorly
names classes and variables, integrated dependencies and bloated functions make the code
error prone and difficult to maintain. Consequences of code breaking range from simple error
message to a potentially deadly safety equipment failure. Software developers should strive for
optimized, refactored code. Most software development project are a group effort, rather than
a solidary activity. Code development in teams was beyond the scope of this report, but the
added benefit from clean code carries over and the individual capable of producing professional
code will make a valuable member to any development team.
RCM Comments https://www.youtube.com/watch?v=2a_ytyt9sf8
REFERENCES:
Martin, R. C. (2009) Clean code: a handbook of agile software craftsmanship. Upper Saddle River,
NJ: Prentice Hall.
Martin, R. C. (2011) Clean Coder: A Code of Conduct for Professional Programmers. Upper Saddle
River, NJ: Prentice Hall.
Martin, R. C. (2019) Clean Agile: Back to Basics. Upper Saddle River, NJ: Prentice Hall.
Se yks Uncle Bobin kirja; clean coder tai vastaava (en jaksa ettiä/kaivella)
Roskis: *Introduced in 1964, BASIC programming language used to have a character limit of two
(2) for variable names. A letter and a number[]. This explains why comments used to be worth
their character count in gold?*. Variable named i4 does not do well to explain its function to
the programmer/reader by name.