You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: refactoring.md
+25-89Lines changed: 25 additions & 89 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,103 +17,39 @@ The bigger a program is, the more important refactoring becomes. In brief, it sa
17
17
18
18
## How to refactor?
19
19
20
-
You should refactor a small program as soon as the program runs and you have a moment to clean up a bit.
21
-
In a bigger program refactoring requires **automated tests**, so that you can check whether you accidentally broke anything.
20
+
You should refactor a program as soon as the program runs and you have a moment to clean up.
21
+
The basic refactoring workflow is:
22
22
23
-
Refactoring means a lot of things:
23
+
1. Open the code in an editor
24
+
2. Pick something you would like to improve
25
+
3. Clean it up
26
+
4. Run the code to see if it still does the same thing
24
27
25
-
* removing unnecessary code
26
-
* splitting long code blocks into functions
27
-
* splitting code into modules
28
-
* extracting classes from the code
29
-
* rewriting statements that are hard to understand
30
-
31
-
On [sourcemaking.com](https://sourcemaking.com/) you find a catalog of refactoring techniques.
28
+
The refactoring workflow is the same for small and big programs.
29
+
But the bigger the program, the more you will need **automated tests**, so that you can check whether you accidentally broke anything.
32
30
33
31
----
34
32
35
-
## What is tech debt?
33
+
## What refactoring strategies are there?
36
34
37
-
If refactoring is ignored a project may accumulate **Technnical debt**.
38
-
**Technical debt** is a frequent problem in projects evolving over time.
39
-
It includes:
35
+
Refactoring means a lot of things. Here are a few basic strategies:
40
36
41
-
* lack of documentation
42
-
* lack of structure
43
-
* badly written code
44
-
* code that breaks in special cases
45
-
* bugs
46
-
* .. and many more
47
-
48
-
This phenomenon has also been described as [**software entropy**](https://en.wikipedia.org/wiki/Software_entropy) and [**Lehmanns Laws**](https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution).
37
+
- rename variable names for clarity
38
+
- move a block of code into a function
39
+
- split a long function into smaller ones
40
+
- remove unnecessary code
41
+
- remove redundant code
42
+
- rewrite statements that are hard to read
43
+
- splitting a Python file into multiple modules
44
+
- eliminate global variables
45
+
- extract a clean data structure
46
+
- extract a class from the code
47
+
- move program logic to a data file (JSON, table or other)
48
+
- add a `__main__` section
49
+
- add docstrings to functions and classes
49
50
50
51
----
51
52
52
-
## How does technical debt emerge?
53
-
54
-
There are at least six reasons why technical debt accumulates:
55
-
56
-
### 1. Haste
57
-
58
-
**Pressure to finish quickly** teases programmers to cut corners. Programmers under pressure try to get the code running, no matter what (*"I can clean this up later."*). Producing clean, transparent, well-tested code becomes a secondary issue. Small nodules of messy code will emerge, grow, accumulate, and if you rush from deadline to deadline, the program becomes a jungle.
59
-
60
-
Slowing down your pace of programming under pressure takes courage.
61
-
62
-
### 2. Misunderstanding the problem
63
-
64
-
When you first write a program, you are making assumptions about the real-world problem it solves. Almost inevitably, some of these assumptions turn out to be wrong. Every time you add new code to correct your wrong assumptions, they will lay a burden on the original design – unless you clean up properly.
65
-
66
-
Because of that, the milestone book *"the mythical man-month"* (Brooks, 1963) states: *"Be prepared to throw one away."*
67
-
68
-
### 3. Lack of experience
69
-
70
-
A programmer might write code that is difficult to maintain because he doesn't know better. An unexperienced programmer thinks that programming means writing code. An experienced programmer - like anyone interested in a book on software engineering - knows that sometimes programming means writing code, and sometimes it doesn't.
71
-
72
-
Lack of experience often results in code that is unnecessary long or complicated. This can happen even to experienced programmers switching from another language. Once, we stumbled upon the following Python code fragment written by a C programmer:
73
-
74
-
:::python3
75
-
i = 0; s = []
76
-
f = open(filename,'r')
77
-
while 1:
78
-
z = f.seek(i)
79
-
if z==None:
80
-
break
81
-
ch = f.read(1)
82
-
s.append(ch)
83
-
i = i+1
84
-
85
-
This code fragment can be written as:
86
-
87
-
:::python3
88
-
s = list(open(filename).read())
53
+
## Where can I learn more?
89
54
90
-
Even though Python is considered easy to learn, writing good Python code is not trivial.
91
-
92
-
### 4. Overabundant experience
93
-
94
-
Experienced programmers can create problematic code, too. In the first place, an experienced programmer is very good to have: They write sophisticated programs incredibly quickly, master new technologies and make them work. Such programmers are rare and valuable.
95
-
96
-
The problem is that sometimes it takes another experienced programmer to understand their code. One example of such code is called **code golf**. In code golf, the programmer tries to implement a program with as few key strokes as possible:
97
-
98
-
The moment an experienced programmer departs and leaves a lot of functional code that is hard to read, the project can suddenly go into debt.
99
-
100
-
101
-
### 5. Python
102
-
103
-
Python checks for SyntaxErrors and the most obvious exceptions at runtime. Unfortunately, Python does not notice much more.
104
-
105
-
Even a simple typo like the following could pass unnoticed:
106
-
107
-
:::python3
108
-
idx = 3
109
-
110
-
...
111
-
112
-
def get_modification_name(ids):
113
-
return DATABASE.get(idx) # should be ids
114
-
115
-
When you move this function to a separate module during a refactoring session, the code will break, thus revealing the bug.
116
-
117
-
### 6. Changes in the environment
118
-
119
-
Even if your program is written perfectly, it will slowly deteriorate. The libraries it uses may deprecate methods, new string encodings, display sizes, new customer wishes and other changes mean that your program is becoming less useful. To stay up to date technically, the code needs to adapt.
55
+
On [sourcemaking.com](https://sourcemaking.com/) you find a catalog of refactoring techniques.
If refactoring is ignored a project may accumulate **Technnical debt**.
7
+
**Technical debt** is a frequent problem in projects evolving over time.
8
+
It includes:
9
+
10
+
* lack of documentation
11
+
* lack of structure
12
+
* badly written code
13
+
* code that breaks in special cases
14
+
* bugs
15
+
* .. and many more
16
+
17
+
This phenomenon has also been described as [**software entropy**](https://en.wikipedia.org/wiki/Software_entropy) and [**Lehmanns Laws**](https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution).
18
+
19
+
----
20
+
21
+
## How does technical debt emerge?
22
+
23
+
There are at least six reasons why technical debt accumulates:
24
+
25
+
### 1. Haste
26
+
27
+
**Pressure to finish quickly** teases programmers to cut corners. Programmers under pressure try to get the code running, no matter what (*"I can clean this up later."*). Producing clean, transparent, well-tested code becomes a secondary issue. Small nodules of messy code will emerge, grow, accumulate, and if you rush from deadline to deadline, the program becomes a jungle.
28
+
29
+
Slowing down your pace of programming under pressure takes courage.
30
+
31
+
### 2. Misunderstanding the problem
32
+
33
+
When you first write a program, you are making assumptions about the real-world problem it solves. Almost inevitably, some of these assumptions turn out to be wrong. Every time you add new code to correct your wrong assumptions, they will lay a burden on the original design – unless you clean up properly.
34
+
35
+
Because of that, the milestone book *"the mythical man-month"* (Brooks, 1963) states: *"Be prepared to throw one away."*
36
+
37
+
### 3. Lack of experience
38
+
39
+
A programmer might write code that is difficult to maintain because he doesn't know better. An unexperienced programmer thinks that programming means writing code. An experienced programmer - like anyone interested in a book on software engineering - knows that sometimes programming means writing code, and sometimes it doesn't.
40
+
41
+
Lack of experience often results in code that is unnecessary long or complicated. This can happen even to experienced programmers switching from another language. Once, we stumbled upon the following Python code fragment written by a C programmer:
42
+
43
+
:::python3
44
+
i = 0; s = []
45
+
f = open(filename,'r')
46
+
while 1:
47
+
z = f.seek(i)
48
+
if z==None:
49
+
break
50
+
ch = f.read(1)
51
+
s.append(ch)
52
+
i = i+1
53
+
54
+
This code fragment can be written as:
55
+
56
+
:::python3
57
+
s = list(open(filename).read())
58
+
59
+
Even though Python is considered easy to learn, writing good Python code is not trivial.
60
+
61
+
### 4. Overabundant experience
62
+
63
+
Experienced programmers can create problematic code, too. In the first place, an experienced programmer is very good to have: They write sophisticated programs incredibly quickly, master new technologies and make them work. Such programmers are rare and valuable.
64
+
65
+
The problem is that sometimes it takes another experienced programmer to understand their code. One example of such code is called **code golf**. In code golf, the programmer tries to implement a program with as few key strokes as possible:
66
+
67
+
The moment an experienced programmer departs and leaves a lot of functional code that is hard to read, the project can suddenly go into debt.
68
+
69
+
70
+
### 5. Python
71
+
72
+
Python checks for SyntaxErrors and the most obvious exceptions at runtime. Unfortunately, Python does not notice much more.
73
+
74
+
Even a simple typo like the following could pass unnoticed:
75
+
76
+
:::python3
77
+
idx = 3
78
+
79
+
...
80
+
81
+
def get_modification_name(ids):
82
+
return DATABASE.get(idx) # should be ids
83
+
84
+
When you move this function to a separate module during a refactoring session, the code will break, thus revealing the bug.
85
+
86
+
### 6. Changes in the environment
87
+
88
+
Even if your program is written perfectly, it will slowly deteriorate. The libraries it uses may deprecate methods, new string encodings, display sizes, new customer wishes and other changes mean that your program is becoming less useful. To stay up to date technically, the code needs to adapt.
0 commit comments