Presenter: Kris Brandow
Liveblogger: Beyang Liu
Our industry has borrowed ideas and practices from a range of industries to improve the design and production of software. In this talk, we’ll look to the publishing industry for ways to improve software development for our industry and within the Go community.
Kris Brandow is senior engineer at MongoDB. He works on the MongoDB Go driver and has been writing Go full-time for nearly 6 years. In addition to programming he also loves to bake and to write.
In programming, we borrow concepts from a lot of other organizations:
We can also borrow from the publishing industry. Kris’s degree is not in computer science, but creative writing and one of the things that first drew him to programming was the parallel between the two. Programming is a form of creative writing.
Writing is highly structured:
Programming is to creative writing as software engineering is to publishing. So let’s pull concepts and ideas from publishing to help us improve the craft of software engineering.
Publishing is has a wide variety of things:
Similarly, in programming, you have libraries, databases, various types of application. These are all very different but all of them go through the same high-level publishing process.
We can borrow 2 things primarily from the publishing industry:
Publishing has things like the Chicago Manual of Style to enforce consistency and shared standards. Go has strong idioms, but no standard manual of style akin to the scope of the Chicago Manual of Style. Go’s culture and values share a lot with that in the publishing industry, but they’ve been doing their thing a lot longer than we’ve been doing ours. So let’s learn from them.
These are the roles of an editor in publishing:
|Acquisition editor||Prototype engineer|
|Developmental editor||Software architect|
|Copy editor||Code reviewer|
|Production editor||Operations engineer|
Borrowing from publishing for code reviews:
Borrowing for codebase structure and maintenance:
A brief story: Kris at one point wound up on a team of one and his manager wasn’t familiar with Go. So who did his code reviews? They decided that an engineer from another team would be “loaned”. This teammate was named Craig and he is the one who likes doing large code reviews. Kris didn’t know this at the time and he submitted a gigantic PR to him and told Craig, “I’m so sorry.” But to Kris’s surprise, he came back the next day and he found a ton of useful comments in Gerrit. Craig told him it was a lot of fun and he learned a lot about Go in the process. One thing that stuck out to Kris was that Craig kept saying, “I’ve left a lot of comments but this is your code. You are making the final decisions and own this code.”
So isn’t a programmer more like a writer, rather than an editor?
Borrowing from the notion of an “editor”:
There are many manuals of style in publishing, but there are two main ones:
There is nothing on the scale of these two style guides in Go. Some projects and companies have tried to adopt a consistent manual of style across the whole team or organization.
What is a manual of style?
There is a hierarchy of manuals of style. At the top are the CMS and AP Stylebook, but each publishing house also has a localized manual of style.
What should go into a manual of style? “Meta” things, NOT “design” things:
The distinction gets a little fuzzy. In a localized manual of style, you may want to enforce consistency in something like middleware that might be a combo of systems “design” and “meta” things.
How do we get started?
But avoid dogma. There is a difference between enlightened consistency and dogmatism. Even experienced adherents to the Chicago Manual of Style will deviate from it. Learn the rules, then break them: