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: _docs/phase1.rst
+93-8
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,11 @@
1
-
Spaghetti
2
-
=========
1
+
(Re)designing code
2
+
==================
3
3
4
-
We begin with a single, linear script in the *elex1/* directory. Below
5
-
are a few reasons why this `code
6
-
smells <http://en.wikipedia.org/wiki/Code_smell>`__ (some might say it
4
+
Code smells
5
+
-----------
6
+
7
+
We begin with a single, linear script in the `elex1/ <https://github.com/PythonJournos/refactoring101/tree/master/elex1>`__ directory.
8
+
Below are a few reasons why this `code smells <http://en.wikipedia.org/wiki/Code_smell>`__ (some might say it
7
9
reeks):
8
10
9
11
- It's hard to understand. You have to read the entire script before
@@ -13,6 +15,86 @@ reeks):
13
15
file.
14
16
- None of the code is reusable by other programs.
15
17
18
+
Hacking-It-Out-As-You-Go
19
+
------------------------
20
+
21
+
Scripts like this are often born when a programmer dives immediately into implementing
22
+
his code. He sees the end goal -- "summarize election data" -- and gets right to it, hacking
23
+
his way through each step of the script until things "work".
24
+
25
+
The hack-it-out-as-you-go approach can certainly produce working code. But unless you're extremely disciplined,
26
+
this process can also yield spaghetti code -- a jumble of hard-to-decipher and error-prone logic that you fear changing.
27
+
28
+
So, how do we avoid spaghetti code? *By choosing to have lots of small problems instead of one big problem.*
29
+
30
+
Lots of small problems
31
+
----------------------
32
+
33
+
A key step in the art of designing code is hitting the breaks up front and spending a few minutes thinking
34
+
through the problem at hand. Using this approach, you'll quickly discover that you don't really
35
+
have one big problem (*"summarize some election data"*) but a series of small problems:
36
+
37
+
* Download election data
38
+
* Parse election data
39
+
* Calculate candidate vote totals and determine winners
40
+
* Create a summary spreadsheet
41
+
42
+
Each of those smaller problems, in turn, can often be decomposed into a series of smaller steps, some of
43
+
which don't become clear until you've started writing the code.
44
+
45
+
But it's critical at this phase to *NOT* start writing code!!! You will be tempted, but doing so will
46
+
switch your brain from "design mode" to the more myopic "code" mode (it's a thing). Trust in your ability
47
+
to implement the code when the time is right (we promise, you'll figure it out), and instead grant yourself a
48
+
few minutes of freedom *to design the code*.
49
+
50
+
If you just can't resist implementing code as you design, then close your laptop
51
+
and go old school with pen and paper. A mind-map or flow-chart is a great way to hash out the
52
+
high-level design and flow of your program. Or if you're lucky enough to have a whiteboard,
53
+
use that to sketch out the initial steps of your program.
54
+
55
+
Some folks also like writing `pseudocode <http://en.wikipedia.org/wiki/Pseudocode>`__,
56
+
though beware the siren call's temptation to slip back into implementing "working" code
57
+
(Python in particular makes this extremely easy).
58
+
59
+
*Fun fact*: Jeremy and I are so enthusiastic about whiteboarding that we once sketched out a
60
+
backyard goat roast on an office wall (said design was never implemented).
61
+
62
+
Shred this code (on paper)
63
+
--------------------------
64
+
65
+
In this tutorial, we already have some ready-baked spaghetti code for you to slice and dice into smaller components.
66
+
67
+
We encourage you to print the code on paper -- yes, dead trees! -- and use a marker to group code bits
68
+
into separate functions. As you to try to make sense of the logic and data structures, it's a good idea to reference the
69
+
`source data <https://docs.google.com/spreadsheet/pub?key=0AhhC0IWaObRqdGFkUW1kUmp2ZlZjUjdTYV9lNFJ5RHc&output=html>`__.
70
+
71
+
This exercise is intended to familiarize you with the data and the mechanics of the code, and get your
72
+
creative juices flowing. As you read the code, think about which sections of logic are related (perhaps they
73
+
process some piece of data, or apply a process to a bunch of data in a loop).
74
+
75
+
Use circles, brackets, arrows -- whatever marks on paper you need to group together such related bits of code.
76
+
Then, try to give them *meaningful names*. These names will become the functions that wrap these bits of logic.
77
+
78
+
`Naming things is hard <http://martinfowler.com/bliki/TwoHardThings.html>`__, and can become *really hard* if a function is trying to do too many things.
79
+
If you find yourself struggling to come up with a clear function name, ask yourself if breaking down the section of code into even smaller parts (
80
+
say two or three functions instead of one) would make it easier to assign a clear and meaningful name to each function.
81
+
82
+
Finally, spend some time thinking about how all these new bits of code will interact. Will one of the functions require an input that comes
83
+
from another function? This orchestration of code is typically handled in a function called `main <http://en.wikipedia.org/wiki/Entry_point>`__,
84
+
which serves as the entry point and quarterback for the entire script.
85
+
86
+
Keep in mind there's no "right" approach or solution here. The overarching goal is to improve the *readability of the code*.
87
+
88
+
Whether you resort to pseudocode, a whiteboard, or simple pen-on-paper, the point is to stop thinking
89
+
about *how to implement the code* and instead focus on *how to design the program*.
90
+
91
+
Once the code design process is complete, try implementing the design. Ask yourself how this process compared to prior efforts to
92
+
write a script (or unravel someone else's code). Was it easier? Harder? Is the end product easier to read and understand?
93
+
94
+
In the next section, you'll see our pass at the same exercise, and learn how to further improve this script by organizing functions into
95
+
new source files.
96
+
97
+
16
98
Questions
17
99
---------
18
100
@@ -28,6 +110,9 @@ Exercises
28
110
---------
29
111
30
112
- Slice up this code into a bunch of functions, where related bits of
31
-
logic are grouped together.
32
-
- Write a unit test for one or more functions extracted from this
33
-
module.
113
+
logic are grouped together. Do function names accurately reflect what they
114
+
actually do? If not, how could you rename functions and/or re-organize the code
115
+
to clarify the purpose of each function?
116
+
- Compare your revised script to `our version <https://github.com/PythonJournos/refactoring101/blob/master/elex2/election_results.py>`__.
117
+
What's similar? What's different? Explain 5 things you like or dislike about each and why.
118
+
- Write a unit test for one or more functions extracted from this module.
0 commit comments