Articles I read this week, including “goodbye clean code,” the Neural ODEs paper retrospective, and technical writing.
Goodbye, clean code
Author: Dan Abramov
How I found this: from /r/programming
Summary: this is a retrospective on how the author (years prior) made a code change that theoretically made the code “cleaner,” by most definitions of the word. In hindsight, the abstractions that they added (which are usually the tradeoff for cleaner code) were unnecessary and made it harder to change the requirements (while, yes, reducing duplication). The author’s boss pulled him aside the next morning to ask him to revert the changes.
Thoughts: the more I think about this, the more I think the post misses the point. The clean code isn’t the problem here: the problems are (1) the author making a code change without consulting the original author (where was code review? why did he commit overnight?) and (2) the author not recognizing that the requirements would change in the future. The original code wasn’t great, and I do think it needed refactoring (make helper functions for the math?), but not in the author’s way. Yes, abstractions have tradeoffs, but the problem wasn’t caused by abstractions in the general sense–it was caused by the use of lousy abstractions. Reducing code duplication has been one of the most effective ways for me to untangle complex codebases.
Sidenote: originally, my “thoughts” paragraph was me just summarizing the article. After thinking some more about it, and reading some of the discussion that happened on Reddit, I switched course and decided that I don’t really like this blog post at all. Disagreeing publicly is tough, though, and I felt a strange pressure to just rehash the important points and say “yeah, good stuff.” Being able to criticize the post is harder.
Bullshit that I and others have said about Neural ODEs
Speaker: David Duvenaud
How I found this: from /r/machinelearning
Summary: this is a research retrospective on the Neural ODEs paper that took place at NeurIPS 2019 (the original paper was at NeurIPS 2018). It’s a short talk (20 minutes) and there isn’t a lot to summarize. Some highlights include the stated motivation being more or less made up, handwaving the non-ML parts (delegating to ODE solvers), and some of the press coverage being misinformed. He Duvenaud brings up the contributions of nice visualizations and a clean title as contributing to the hype.
Thoughts: I don’t understand this paper nearly well enough to comment on the substance, but I really appreciate the idea of research retrospectives. Reflecting on one’s successes is not nearly as common as reflecting on failures, and watching this talk brings down a paper that received a lot of attention to a more ordinary level. It also reminds me that even these prolific papers have hacks and kludges, which Duvenaud discusses.
Radical Candor, Software Edition
Author: Rina Artstain
How I found this: from https://pointer.io
Summary: this is an article extending the principles in Kim Scott’s book Radical Candor to a software engineering team. Radical Candor has two key principles, “care personally” (about the people you work with or manage, treating them as people and not just employees), and “challenge directly” (by giving clear, actionable feedback and being direct with others). The article’s author extends this to the code and design review settings, encouraging engineers to approve code reviews with comments and to take care to make sure everyone on a team has a voice in a design review.
Thoughts: this, I think, is really useful for someone who hasn’t read Radical Candor. For someone who has, it doesn’t add a ton of value; there’s not that much in Radical Candor that isn’t applicable to software engineers right out of the gate. Even as a non-manager, I’ve found the book to have transformed my relationships at work.
More broadly, though, this is an instance of “tech isn’t special,” where workplace advice or traditional wisdom gets extended to the software engineering setting without a real need. Many of the problems that tech teams face are not tech-specific, especially the interpersonal ones.
One example from the article is the quote “It’s not just code. It’s our work. And we’re emotionally invested in it,” referring to how code reviews often forget the person behind the code. I absolutely agree–that’s happened several times at my company–but the same is true of any work that anyone does that receives feedback, code or otherwise.
And, to be clear, there are ways in which tech is special; the companies pushing the limits of scalability or making breakthroughs in AI research are certainly in uncharted territory. The ease and speed at which software systems can impact society is both unprecedented and alarming. But I am not yet convinced that workplace relationships are one of those ways.
Notes on Technical Writing
Author: Marcus Kazmierczak
How I found this: from Pointer
Summary: these are literally the author’s notes on technical writing. There are principles to follow, discussions on minimalistic instruction and on the types of documentation, and resources to more.
Thoughts: bookmarked this. One of my responsibilities on a previous team was rebuilding all of the documentation for an internal software framework. Some of this was mechanical, like migrating pages from Confluence, Google Drive, PRs, etc., to a Sphinx-built site. The majority of the work, though, was reorganizing the documentation and consolidating and reworking disparate resources. I came up with my own ideas for technical writing then, so seeing someone else’s is great.