Thanks for this! It’s helpful to hear things framed from a different person’s perspective. In particular, the way you explained “complex systems have to be broken into parts, and parts have to be understandable without opening the box”.
But there’s more on the box than the function’s name, and you should make use of all of it, for exactly the reasoning in this post!
Great point! I have to admit, I didn’t know that docstrings existed until now. Kinda funny that I wrote this post without knowing what docstrings are. I’m really excited to use them in my next project now.
and their boundary is their (i) name, (ii) doc string, and (iii) type signature.
Actually, one of my crazy ideas is to extend this boundary even further with visuals. (Well, in that post I wasn’t necessarily talking about it as part of the “hover over a line of code in a text editor interface”, but it could fit there.)
How can you tell if it “does one thing”? Write the module’s docs, which should include a high-level overview of the whole module, plus shorter docs for each function in the module.
Ah that makes sense. Sounds like a good forcing function.
I’m sorry you don’t have a good naming buddy! Everyone should have a naming buddy; it’s so hard to come up with good names on your own.
Yeah. In a perfect world I’d actually do something along the lines of low-fi usability testing with people. But instead of testing whether they understand a UI, testing whether they understand my code.
Thanks for this! It’s helpful to hear things framed from a different person’s perspective. In particular, the way you explained “complex systems have to be broken into parts, and parts have to be understandable without opening the box”.
Great point! I have to admit, I didn’t know that docstrings existed until now. Kinda funny that I wrote this post without knowing what docstrings are. I’m really excited to use them in my next project now.
Actually, one of my crazy ideas is to extend this boundary even further with visuals. (Well, in that post I wasn’t necessarily talking about it as part of the “hover over a line of code in a text editor interface”, but it could fit there.)
Ah that makes sense. Sounds like a good forcing function.
Yeah. In a perfect world I’d actually do something along the lines of low-fi usability testing with people. But instead of testing whether they understand a UI, testing whether they understand my code.