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: README.markdown
+38-17Lines changed: 38 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,16 @@
2
2
3
3
A compendium for self-education about "data structures and algorithms," created by and for "people without computer science degrees."
4
4
5
+
1.[Motivation](#motivation)
6
+
1.[How to use this repository](#how-to-use-this-repository)
7
+
1.[Running the code](#running-the-code)
8
+
*[JavaScript](#javascript)
9
+
*[PHP](#php)
10
+
*[Python](#python)
11
+
*[Ruby](#ruby)
12
+
1.[About code comments](#about-code-comments)
13
+
1.[Exercise suggestions](#exercise-suggestions)
14
+
5
15
## Motivation
6
16
7
17
Core computer science concepts, such as "data structures and algorithms," are taught using a classist, fucked-up pedagogical approach that makes me viscerally, incoherently angry. Nevertheless, I would like to know what the fuck people mean when they say things like "data structure" or "algorithm" and refer to specific structures or specific algorithms. Despite 20 years of practical programming experience, working in a variety of Information Technology sectors, I still feel completely lost when attempting to navigate this area of specialized knowledge.
@@ -26,23 +36,6 @@ I strongly encourage you to actually run and play around with the code itself. D
26
36
27
37
Better yet, *debug* them yourself. This doesn't mean that there are bugs in the code. There aren't. (At least, I hope there aren't!) Instead, it means use your language's built-in debugging tools to inspect the code at each stage of its operation. This section will explain how to do that in more detail.
28
38
29
-
#### [Python](https://python.org/)
30
-
31
-
The Python code samples are all compatible with both [Python 2.7](https://docs.python.org/2.7/) and [Python 3](https://docs.python.org/3/) versions. To run them, execute them like this at a command shell:
32
-
33
-
```sh
34
-
# to run the iterative implementation of the binary search algorithm example
35
-
python binary_search/binary_search_iterative.py
36
-
```
37
-
38
-
Python's built-in debugger is called [`pdb`](https://docs.python.org/3/library/pdb.html). To debug the code samples, execute them like so:
39
-
40
-
```sh
41
-
python -m pdb binary_search/binary_search_iterative.py # debug the binary_search_iterative.py example
42
-
```
43
-
44
-
You can use the debugger to run one line of the code at a time, and it will allow you to inspect the values of all the variables during program execution. Once in the debugger, type `help` to get help. (The `pdb` help is pretty good, but feel free to hop into the [Better Angels's public chat room](https://gitter.im/betterangels/better-angels) if you need help from a human.)
The JavaScript code samples are all compatible with [NodeJS](https://nodejs.org/) and all modern Web browser consoles because they conform to [ECMAScript 5](https://en.wikipedia.org/wiki/ECMAScript#5th_Edition). You can run them in a shell at a command line, or you can copy-and-paste them into the JavaScript console in your browser's developer tools.
You can use the debugger to run one line of code at a time, and it will allow you to inspect the values of all the variables during program execution. Once in the debugger, type `help` to get help. (The `phpdbg` help is verbose but not very intuitive, so feel free to hop into the [Better Angels's public chat room](https://gitter.im/betterangels/better-angels) if you need help from a human.)
93
86
87
+
#### [Python](https://python.org/)
88
+
89
+
The Python code samples are all compatible with both [Python 2.7](https://docs.python.org/2.7/) and [Python 3](https://docs.python.org/3/) versions. To run them, execute them like this at a command shell:
90
+
91
+
```sh
92
+
# to run the iterative implementation of the binary search algorithm example
93
+
python binary_search/binary_search_iterative.py
94
+
```
95
+
96
+
Python's built-in debugger is called [`pdb`](https://docs.python.org/3/library/pdb.html). To debug the code samples, execute them like so:
97
+
98
+
```sh
99
+
python -m pdb binary_search/binary_search_iterative.py # debug the binary_search_iterative.py example
100
+
```
101
+
102
+
You can use the debugger to run one line of the code at a time, and it will allow you to inspect the values of all the variables during program execution. Once in the debugger, type `help` to get help. (The `pdb` help is pretty good, but feel free to hop into the [Better Angels's public chat room](https://gitter.im/betterangels/better-angels) if you need help from a human.)
103
+
94
104
#### [Ruby](https://www.ruby-lang.org/)
95
105
96
106
The Ruby code samples are all compatible with Ruby 2.0 and newer. To run them, execute them like this at a command shell:
You can use the debugger to run one line of code at a time, and it will allow you to inspect the values of all the variables during program execution. Once in the debugger, type `help` to get help. (Ruby's debugger help is somewhat limited, so feel free to hop into the [Better Angels's public chat room](https://gitter.im/betterangels/better-angels) if you need help from a human.)
110
120
121
+
### About code comments
122
+
123
+
In addition to containing detailed inline code comments, each example is also formally documented using the best practices of the language in which the example code is written. Formal documentation means that the files, classes, class members, methods, functions, arguments of each function, and other relevant implementation details are accessible by tools that automatically generate a programmer's manual for how to use the class, method, or function implemented by the example. Each language has its own de-facto standard tool for this:
124
+
125
+
*[JSDoc](http://usejsdoc.org/) is used for documenting the JavaScript code samples.
126
+
*[PHPDoc](https://phpdoc.org/) is used for documenting the PHP code samples.
127
+
*[Google-style Python docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) are used for documenting the Python code samples. Additionally, the Python code samples embed [`doctest`s](https://en.wikipedia.org/wiki/Doctest) to show example usage and output.
128
+
*[RDoc](http://rdoc.sourceforge.net/doc/index.html) is used for documenting the Ruby code samples.
129
+
130
+
I've done this in order to habitualize novice programmers to reading (and hopefully writing) such auto-generatable documentation. Since each code sample is self-contained and relatively small, this also provides a good opportunity to practice installing, using, and tweaking the formatting or output of such automatic code documentation tools, if you want to do that. (I recommend it.)
131
+
111
132
## Exercise suggestions
112
133
113
134
In addition to running the code samples, I suggest you try one or more of the following exercises with each sample. It's more fun if you can find a friend to do them with. This is called "pair programming" (or just "pairing" for short), and it works a little bit like the way a pilot and co-pilot collaborate when flying a plane: one person has their hands on the keyboard (the "driver") and the other person suggests things to try (the "navigator"). Switch up who's driving and who's navigating as often as you feel comfortable, but try to make sure one of you isn't monopolizing one role or the other. (You might be surprised how much you can learn from navigating rather than driving, or vice versa, if you're not used to it.)
0 commit comments