Thread Reader

This is a brilliant question from a non-coder. The short answer is "you don't" The longer answer is that there are different levels of code review with different types of usefulness. Let's use an analogy: Suppose I am a journalist writing an article on a civil rights protest...



Question from a non-coder. How do you review code without knowing its purpose and running tests to check it. Looking at a printed page seems pretty useless to me.
I finish my article, and ask an editor to review my piece. The article is written in French. At the lowest level, the editor makes sure that I understand the French language, and that each sentence is grammatically correct.
At the next level, the editor makes sure that the article is structured like a real article. Broken up into paragraphs, and that each paragraph follows on from the previous one, etc Next level, that the size of the article is appropriate: 1 sentence too short, 10 pages too long.
At the next level, the editor makes sure that the article uses the right vocabulary, sentence structure, and voice for the audience. Now is not the time for the writer to show off an impressive vocabulary or knowledge of grammatically correct but arcane sentence structures.
You'll notice that up until this point, the editor hasn't even addressed accuracy, factual correctness, framing, appropriateness of topic, fairness, journalistic ethics, or any of the topics that editors should worry about. Or the big one: should this article even exist?
In order to answer any of those questions, the editor needs to combine the article that I've written, with two other important sources of extra information (metadata). 1. Context about the publication the article will appear in 2. Context about the need that this article solves
I can provide *some* context on 2 with a post-it note that I attach to my article: "This covers the protest at blah, driven by blah. It's part of our ongoing series covering blah. I tried to interview X but their office declined again. Hoping to get into this month's issue."
But a lot of "context 1" requires experience of the environment the article will appear in. * What previous articles have been written on this topic? * Is this topic controversial? If so, why? * What biases might the writer not be aware of? Who did they not think to talk to?
The Guardian is a highly effective publication. Their editors can do a lot in 15 mins. But even given 2 hours, an editor for the Guardian would struggle to edit an article written for an English language publication in Gambia, covering a protest of corruption at a local factory.
Code is very similar. Most of the senior engineers at tech companies have a strong enough command of several programming languages, that there is little value in the "grammar" part of code reviews. I mean sure, everyone makes typos, and anyone can write an ambiguous sentence.
But most of the value of code reviews is in engineers serving as peer-editors for each other on much higher level concerns. This analogy also works with the "write more code!" sillyness that's taken over. Writing more code every week can be bad. Here's one reason why...
Suppose in my article example, about the factory protest, I'd interviewed factory owners, local politicians, and the police... but I hadn't interviewed *any* of the protestors, and the factory's biggest customer supported the protest, and was close to going on record.
A good editor would say, "Get the whole story." A bad editor might say, "What did you publish this week? Every writer must publish something clever and witty every week, or fired! Show me your most impressive sentence!"
Anyway, long thread to say that your instincts are right.👍🏿 On a completely unrelated topic, the State of California doesn't like layoffs disguised as "firings for cause." It's kinda European that way.
Oh, and obligatory: Newspapers should not platform anti-trans rhetoric. We all know where that leads. Stop it. Be better.
Mekka 💉x4
Building digital ecosystems at Google, but opinions my own. He/him. Black Lives Matter
Follow on Twitter
Missing some tweets in this thread? Or failed to load images or videos? You can try to .