If you’re lucky enough to bump into Werner Vogels, CTO of Amazon, on a lazy Sunday afternoon in Amsterdam, you might do what this person did and ask, “How should we think different about software development?”
To which Vogels replied, “Your software needs to be operated for decades longer [than it takes for] you [to] write it.”
While this means the software would qualify as legacy, that’s just an indication that you wrote something people still want to use, years or decades later. However, it’s not always easy to deliver the kind of longevity that Vogels implies developers should aspire to deliver.
Things are about to get boring
I’ve written before about why boring is good when it comes to choosing enterprise tech like databases. An enterprise’s first consideration is to stay in business, keep applications running, etc. As such, choosing solutions with well-understood capabilities and well-understood failure modes is important.
SEE: How to build a successful developer career (free PDF) (TechRepublic)
But there’s another aspect to “boring” and applications, and that involves taking the most basic approach to solving a particular business problem. As developer Manuel Odendahl has noted, he manages to “consistently create products of great value” with code that is “very dumb” without “crazy maths” or wacky AI. Instead, his secret is to “ask a lot of questions” so as to “understand what information the business needs, in contrast to the data it actually processes.”
By asking questions to hone in on exactly what information the application needs to consume and distribute to meet a business need, he’s able to keep the application simple.
“The simpler the path that the information takes to get from A to B, the better the system becomes. Because we asked the right questions, the software is aiming straight for the bull’s eye, solving the actual business problems.”
That’s a hugely valuable, and often overlooked, principle that is key to the long-term supportability of software. This becomes even more important because, as AWS engineering executive Matt Wilson correctly called out to Vogels, “Software running in an operational system is rarely done being written.”
By keeping code as clean or svelte as possible, developers make it easier to improve months, years or decades later. This is also where good documentation comes in.
If you didn’t document it, it didn’t happen
Good documentation begins, developer advocate Mason Egger stressed (as captured by David Cassel at PyCon 2022), with the same basic principle Odendahl highlighted—keeping things simple. In the case of documentation, Egger noted that developers should articulate a clear goal the documentation will help its readers achieve. There is no need to overwhelm the reader with excess verbiage; the developer is in the docs to get something done, so give them all that is needed to accomplish that job, and don’t waste their time with more.
SEE: Hiring kit: Python developer (TechRepublic Premium)
According to Egger, more often than not, a developer will skip straight to the sample code rather than the explanation, which is why he argued for using real-world examples. Egger also highlighted the need to make docs easily searchable, so a reader can quickly find the information they need. It’s also important to write as simply as possible, without using jargon or unnecessarily complicated words. The goal is always simplicity and brevity.
With code samples and explanatory text, it’s also important to double-check that you haven’t inadvertently left errors in the docs.
“The only thing worse than no documentation is incorrect documentation,” said Egger. “Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time.”
These (and other) documentation tips help to ensure that someone encountering sample code days, weeks or years later can more easily understand it, which, in turn, means they’re more likely to use it. Thus, the software itself, as well as the documentation for it, needs to be as straightforward as possible today to make it readable and usable for many tomorrows to come.
Disclosure: I work for MongoDB, but the views expressed herein are mine.