To be an engineer is to be a storyteller.
While it might sound far fetched, these professions have more in common than one might think. Just as reading this article without any punctuation or paragraphs would be confusing, code without documentation to explain why, how and what it does would be similarly bewildering.
CODE DOCUMENTATION, DOCUMENTED
Per the management platform, Swimm, effective code documentation might include:
- Comments within the code.
- External documentation such as user manuals, technical specifications and design documents.
- Internal documents like coding guidelines, standards and conventions.
It comes down to the importance of narrative.
When code has a clear beginning, middle and end, it naturally forms a narrative arc that guides other programmers. This not only enhances readability but fosters smoother collaboration and maintenance.
This is the perspective of Red Canary Senior Software Engineer Hilary Stohs-Krause, whose unique transition from journalism to tech has helped her set the standard for engaging code for over a decade.
“Code should be easy to follow,” she emphasized. “The aim is to facilitate future engineers’ understanding of the code’s purpose and enable them to make modifications confidently and with clarity.”
Built In Colorado recently sat down with her to learn more about what differentiates her approach.
Red Canary empowers security professionals to transform their organization’s information security.
Describe one of the principles, habits or rituals that differentiates your engineering approach.
I’ve been an engineer for 11 years, but my first passion — and profession — was journalism. When I transitioned into tech, I brought various best practices from writing articles and adapted them for writing code.
Say that I’m writing an article about the impact of pesticides on a local community: I’d collect information from stakeholders, testimonies from residents, legalese from government officials and technical data from scientists. Then, I’d collect and structure this information so people from all backgrounds could engage and gain an understanding of the issue.
Crafting code is similar — especially at a company with a large and complicated code base. We start with an idea and collaborate with stakeholders to gather requirements like business case from product, human element from customer support and usability from design, and then take that information and give it structure.
What differences have you noticed as a result?
This time, it’s variables and methods instead of nouns and verbs. Our audience isn’t the general public, but fellow engineers at our company, and our code becomes a story to help them understand the idea’s implementation. I focus on narrative to make my code as understandable, clean and adaptable as possible. It comes into play when I think about the order of my method and how I name and structure my unit tests. It’s avoiding acronyms and pulling out variables to serve as guideposts. It’s writing documentation that doesn’t make assumptions and liberally using “context” in my RSpec code.
What does this approach help you and your team accomplish?
Focusing on narrative in the software engineering process has multiple benefits, both for engineers and the business at large and it makes it easier for me to stay organized. If I’m starting to spin my wheels or move too fast, returning to the narrative helps me recalibrate. When I’m successful at maintaining a narrative, it’s also easier for code reviewers. The goal is to write code that’s not only logical and methodical, but that also tells a story.
“The goal is to write code that tells a story.”
