My bag of tricks – loose notes, design patterns, rules-of-thumb
gordonbrander.com
gordonbrander.com
In the old times, many Germanic scholars would build a similar thing using flashcards. It was called a zettelkasten.
I have recently switched all my note-taking and task/todo management to org-mode, but I'm still figuring out how to use it properly. At the moment, I just have a personal.org, refile.org and project specific .org files, all kinda taking the shape of headings with sub-sub-sub-sub-headings inside until there is either none or some content inside, but a personal wiki, it doesn't feel like. It feels more like ordered mess, kinda. It's definitely better than anything I've ever used before.
Any good tips you want to share?
org-mode is a bit like C++ or LaTeX. I say this as a good thing. It has tons of features, but you need to choose what to use and what to keep out.
For me, something that works great is to keep all org files in the same folder, with a flat structure. That includes my task list and my calendar. I version control everything, except organizational things that change often instead of growing like articles. I also keep out of version control first quick drafts of any article.
The standard Emacs function for prompting for data with autocomplete is completing-read. You could build an elisp function that prompts for the name of a wiki file with completing-read, and then visits it. The autocompletion will be provided by whatever package you have configured globally - be it Helm, or Ivy, or something else.
A quick example how I started using this feature - I have my half-done invoicing system (for turning time clocked on org-mode tasks into PDF invoices). An entry point to invoicing a customer may look like this:
(defun invoice-customer (customer-name)
(interactive (customers--completing-read-customer))
;; TODO Create an org document containing the invoice table and link.
(message "Invoicing %s" customer-name))
(defun customers--completing-read-customer ()
"To be used as a value of `INTERACTIVE' declaration for functions that need to read a customer value."
(list (completing-read "Customer: " (mapcar #'car *customers/customers*) nil t nil nil *customers/current-customer*)))
Or, instead of all that, you can do what I actually do for the wiki - bookmark the wiki folder itself (with C-x r m in a dired buffer), and use C-x r b foldername to jump to it, and use incremental search in the resulting dired buffer to find the entry you need.
Knowledge pays compound interest: the more you know, the easier it is to learn new stuff (more branches on the semantic tree). Just jotting down simple unconnected facts and organizing them later has helped me become a much competent person.
I'm thinking about publishing a subset of it, but at this point it's one big mix of general knowledge and pretty personal stuff.
Also some other wikis have similar principles, for example: https://tiddlywiki.com/static/Philosophy%2520of%2520Tiddlers...
https://takingnotenow.blogspot.com/2007/12/luhmanns-zettelka...
https://takingnotenow.blogspot.com/2016/09/luhmanns-zettelka...
https://takingnotenow.blogspot.com/2016/08/my-translations-o...
And, just for quick reference, his entire 'zettelkasten' tag:
https://takingnotenow.blogspot.com/search/label/Zettelkasten
Anyone feeling honest resonance with your words should read the book. I can't put it in other words.
In fact, the book itself has two audiences - the problem solver, and the teacher of future problem solvers (with the suggestion that if you're the former, you can also be the latter by talking to yourself). So the book gives you both a bunch of stuff to internalize, and a discussion on how to teach that stuff to other people.
--
Tangentially, reading this is making me do some serious soul searching about the way I approach programming. For instance, Polya emphasizes reviewing your work as an important step in solving a mathematical problem - not (just) to re-check correctness, but to spend some time thinking about the structure of your solution, and learn something from it. This is something I just realized I rarely do in programming - I don't review my code to learn more from the very solution I just implemented. I usually just commit and continue to the next thing. This is a thing I'm going to work on changing.
That said, I think it's worth investing your own time in doing it. I feel a lot more at ease when I take time to think about my work, and I think it pays off in my own career in the long run, even if it costs me some of my own time.
> The big idea is "messaging" - that is what the kernal of Smalltalk/Squeak is all about (and it's something that was never quite completed in our Xerox PARC phase). The Japanese have a small word - ma - for "that which is in between" - perhaps the nearest English equivalent is "interstitial".
Bill Kerr once said that point of view is worth 80 IQ points. I think the above statement is a good example.
It's simple enough to seem too trivial to write down. Yet years of work and failure could stand behind it. All too easy for beginners to ignore and trace the same frustrating path.
I've been trying to introduce this into my current company for as long as I've been working there, with no success so far, with varying reasons:
- Unit tests for existing projects often fail - Unit tests for existing projects take several minutes to run - Our current build process cannot be automated.
Quite frustrating, especially since I've seen a lot of cases where it could've saved us from near-disasters.
EDIT: I think on the subject of Emergence, the writer has missed one key point: emergence requires interplay between different levels of the system.
Same here. Except we have no almost no unit tests because
1) Most of the devs don't know how to write unit tests 2) Most of the devs don't know hot to write code that is testable, even if they could write the actual unit tests.
About a year or so ago we had a project that got a few unit tests added to it, within days they were broken nad failing. The dev just added a [TestCategory("Blah")] and excluded them from being run...
> 1) Most of the devs don't know how to write unit tests
> 2) Most of the devs don't know hot to write code that is testable, even if they could write the actual unit tests.
Sounds really familiar... I'd like to add the following one:
> 3) Cannot make the distinction between code that needs unit testsand code that does not need unit tests
Others may be more able to find you more readily available sources.
You see, I've read that. I've read one other book on unit tests too, and been on 2-day long training in TDD, and spent many hours trying to write unit tests, and yet the skill still eludes me. It's like I have a blind spot there, because I can't for the best of me figure out how to test most of the code I write.
In the projects I'm working on, I find roughly 10% of the code to be unit-testable even in principle. That's the core logic, the tricky parts - like the clever pathfinding algorithm I wrote for routing arrows in diagrams, or the clever code that diffs configurations to output an executable changeset (add this, delete that, move this there...). This I usually write functional-style (regardless of language), I expect specific inputs and outputs, so I can test such code effectively. Beyond that, I can also test some trivial utilities (usually also written in functional style). But the remaining 80-90% of any program I work on turns out to be a combination of:
- code already tested by someone else - external dependencies
- code bureaucracy, which forms vast majority of the program - that is, including/injecting/managing dependencies, moving data around, jumping through and around abstraction layer; this I believe is untestable in principle, unless I'm willing to test code structure itself (technically doable for my Lisp projects...)
- the user interface, the other big part, which is also hilariously untestable, and rarely worth testing automatically, as any regression there will be immediately noticed and reported by real people
I'm having trouble even imagining how to unit-test the three things above, and it's not something covered in unit testing books, tutorials or courses I've seen - they all focus on the basics, like assertions and red-green-refactor, which are the dumb part of writing test. I'm looking for something for the difficult part - how to test the three categories of code I mentioned above.
You test for whether the integration works correctly, for example if you use a library for computation you will test whether your function which uses the library is producing the expected result
> - code bureaucracy, which forms vast majority of the program - that is, including/injecting/managing dependencies, moving data around, jumping through and around abstraction layer; this I believe is untestable in principle, unless I'm willing to test code structure itself (technically doable for my Lisp projects...)
Here again you do some integration testing, for example when handling database operations, you can setup a test to load fake data in the database, run operations on this fake data and compare the results, and then purge the fake data.
> - the user interface, the other big part, which is also hilariously untestable, and rarely worth testing automatically, as any regression there will be immediately noticed and reported by real people
This sort of testing has become much more common for web apps and mobile apps, there are two things being tested one is whether the interface loads correctly under different conditions(device types, screen resolutions etc) this is tested by comparing the image for the 'correct' configuration with the test results, the other thing is whether the interface behaves correctly for certain test interactions - this is tested by automating a set of interactions using an automation suit and then checking whether the interface displays/ouputs the correct result.
I've also struggled with this notion of "untestable" code. Untestable code seems to usually be a big pile of function calls. Testable code seems to be little islands of functionality which are connected by interfaces where only data is exchanged.
Practically, this seems to be about shying away from interfaces which look like 'doThis()', 'doThat()', and more like 'apply(data)'. Less imperative micro-management and more functional-core/imperative-shell.
Edit: a network analogy might be: think about the differences between a remote procedure call API vs. simply exchanging declarative data (REST).
In other words, I agree with you, but would question why you're even _trying_ to unit-test those other areas that aren't conducive to unit testing.
> In other words, I agree with you, but would question why you're even _trying_ to unit-test those other areas that aren't conducive to unit testing.
Well, other people make funny looks at me when they see how little tests I write...
No, but honestly, I see so much advocacy towards writing lots of tests, or even starting with tests, and so I'm trying (and failing) to see the merit of this approach in the stuff I work on.
> you'll almost-certainly embed the same assumptions you're attempting to test into the tests themselves.
That was my main objection when I was on a TDD course - I quickly noticed that my tests tend to structurally encode the very implementation I'm about to write.
4) Don't know how to mock effectively
I've seen three flavours of this one:
- tests that take forever because they don't mock a slow external process that gets called 100s of times in the suite.
- tests that randomly break because someone left a file in /tmp/ or some other lack-of-isolation mystery.
- tests that run like shit off a shiny shovel, because everything is mocked, meaning that nothing is actually tested.
Can you expand on this a bit?
I've always worked under the impression that tests should be focused on testing a narrow slice of code. So if my SUT has some dependencies, those will be mocked with the expected result from the dependency, and possibly even with the expected parameters in the arguments. The asserts will check the result from the SUT, but also that the expected method on the mock was called. This way, I'm just testing the code for the SUT, nothing more.
In that project's case, 99% of tests were mocks where the only thing being tested was whether or not the mocked function got called the expected number of times or with expected arguments.
So the many thousands of tests ran very quickly, and over 90% of the code was covered by tests; however, nothing was actually being functionally tested in those cases.
In other words, the tests ran like shit off a shiny shovel.
What then happens is that the mocked out functions change what they return, or the order of what they do inside (e.g so that for a given set of inputs now throws a different exception). Someone forgets to update the mocks. All the tests continue to pass, even though none of the conditions are actually possible in the program.
Your "expected result from dependency" might be volatile or hard to mock due to bugs, state, timing, configuration, unclear documentation, version upgrades or other factors inside the dependency. So when the system breaks while all unit tests are still passing you get this blame-game where one team is accusing the dependency for not behaving as they expect, when the truth is that the interface was never stable in the first place or was never meant to be used that way.
What you have to do is to choose your ratio of system test vs unit test. The scenario GP describes is companies that spend 99% of their testing budget on unit test and 1% on system test, instead of a more healthy 40-60.
Unit testing is easy for beginners. Unit testing done well is much less so. This results in many inexperienced people writing poor unit tests.
In my last job, I worked on a legacy C++ code base. 500K lines of thorough testing, but none was a unit test. It took 10 hours to run the full test suite. I set about the task of converting portions for unit testability.
I was surprised how much of a challenge it was (and I learned a lot). There were few resources on proper unit testing in C++. Mostly learned from Stack Overflow. Lessons learned:
1. If your code did not have unit tests, then likely your code will need a lot of rearchitecting just to enable a single unit test. The good news is that the rearchitecting made the code better.
As a corollary: You'll never know how much coupling there is in your code until you write unit tests for it. Our code looked fairly good, but when I wanted to test one part, I found too many dependencies I needed to bring in just to test it. In the end, to test one part, I was involving code from all over the code base. Not good. Most of my effort was writing interface classes to separate the parts so that I could unit test them.
2. For C++, this means your code will look very enterprisey. For once, this was a good thing.
3. Mocking is an art. There's no ideal rule/guideline for it. Overmock and you are just encoding bugs into your tests. Undermock and you are testing too many things at once.
4. For the love of God, don't do a 1:1 mapping between functions/methods and tests. It's OK if your test involves more than one method. Even Robert Martin (Uncle Bob) says so. I know I go against much dogma, but make your unit tests test features, not functions.
5. If your unit tests keep breaking due to trivial refactors, then architect your unit tests to be less sensitive to refactors.
6. For classes, don't test private methods directly. Test them through your public interface. If you cannot reach some code in a private method via the public interface, throw the code away!
7. Perhaps the most important: Assume a hostile management (which is what I had). For every code change you make so that you can write a unit test, can you justify that code change assuming your project never will have unit tests? There are multiple ways to write unit tests - many of them are bad. This guideline will keep you from taking convenient shortcuts.
This advice is all about unit tests, and not TDD. With TDD, it is not hard to test yourself into a corner where you then throw everything away and restart. If you insist on TDD, then at least follow Uncle Bob's heuristic. For your function/feature, think of the most complicated result/boundary input, and make that your first unit test. This way you're less likely to develop the function into the wrong corner.
When I completed my proof of work, the team rejected it. The feedback was it required too much skill for some of the people in the team (40+ developers across 4 sites), and the likelihood that all of them will get it was miniscule. And too much of the code would need to change to add unit tests.
I later read this book:
https://www.amazon.com/Art-Unit-Testing-examples/dp/16172908...
And it contains quite a bit of what I learned from unit testing.
Think of it this way: Any time the build is broken, everyone working on the project is interrupted. If you have 10 people working on the codebase and the build is broken for an hour, that's a whole workday and then some wasted.
You could start a grassroots movement - create a pre-push or pre-commit hook that runs tests before it ends up on the remote. Don't worry about the tests taking minutes to run, if you're waiting on that several times a day you're probably publishing too many small changes over the course of a day.
You don't understand; they are continually broken on master.
Furthermore, you assume that we only commit to master after reviews etc have been done. This isn't the case. Commits, even intermittent commits, are pushed to master, and reviewed from there.
I think most people would agree that's an objectively wrong way to do it.
You can do a lot of things between bash scripts, PowerShell, etc. Even custom executables.
Assert(rand() % 2 == 0);
When the test gets run the first time, it can pass and the code can be admitted, but when the next person goes to add code, it can fail. At this point, you've broken your defining principle: that all the code in the test base is correct. The answer of what to do here isnt clear as its a tradeoff in time spent fixing the tests (or potentially the test framework) and developing features. If you have deadlines this becomes more tenuous. Then you figure out that the reason the test is flaky is because it isnt being run in a real environment...etc.
All I'm saying is that it isnt as simple as this "Rule" would like to have you believe.
That’s the idea ... bring back the joy of blogging and meantime capture and grow knowledge.
This post reminds me of some PG essay I once read (too lazy to look it up). Did you use the PG essay as reference material? Because if yes it might be nice to put some links that served as inspiration for the article?
It’s a good book which would also be great as a set of prompt cards IDEO style.
Edit: On a whim I googled and it does exist as a card deck as well!
Why Toys - https://blog.ycombinator.com/why-toys/
The Next Big Thing Will Start Out Looking Like a Toy - http://cdixon.org/2010/01/03/the-next-big-thing-will-start-o...
I suspect the main value of this particular list was actually producing the list, and mainly for the author's sake.
The presentation is actually pretty, and I'm glad people share their favorite learning/knowledge resources. But I guess I'm coming mainly from my frustration of finding so many things interesting but so hard to choose what to focus my attention on.
He talks a lot about 'trails' the people create, so I think the idea is that you'd be able to take this set of notes and links and integrate it with your own set.
(I've got the blog and the domain set up, I just need to start adding content).