Be Transparent

My sister and I have chosen incredibly different career paths. She does graphic design for a multinational corporation and I… Well, I have chosen the path of writing software.

Over the years, it’s been fun to discover places where ideas from our professional lives intersect into each others’ fields. Two of these realizations came to me back when she was still in college / art school and have been among my guiding principles ever since.

First, one should never, ever, ever use Comic Sans. (Enough said.)

Second, and almost as obvious, the best way to get better at your craft is to encourage and accept constructive criticism.

For four very long years, my sister would repeatedly spend hours working on projects for her classes. She poured her heart and soul into nearly every project she was assigned, only to have her work ripped apart by her professors and peers in class the next day. A couple of times the criticism got to her but overall, she learned to accept and learn from the critical feedback she receives.

Criticism like this seems to make a lot of sense in the subjective world of creatives but… What about software design and development? — To answer with another question, riddle me this: If two independent teams are given identical non-trivial software requirements, how alike with their resulting implementations be?

Answer: Not much. 99.9% of the time the solutions will be unique. It turns out, software is a creative expression of the people involved in designing and writing it.

Why aren’t critiques a cornerstone of computer science education as well? — If we aren’t careful, it is often way too easy for software engineers to become attached to our code, holding it up on pedestals it doesn’t deserve.

In corporate settings, we often struggle to iron out inconsistencies in code bases. We create Coding Standards to make code look consistent and try to conduct Code Reviews to discover problems and enforce the coding standards. Unfortunately, my personal experience has shown that the code reviews and coding standards are difficult to implement effectively. Some of the many reasons include:

  • there’s never enough time to conduct thorough reviews
  • code reviews are boring and it’s always more fun to chase new things
  • complicated code can be hard to follow
  • leaky abstractions are… leaky

Reviewing software is often harder to do effectively than the act of writing it in the first place. Wait. This is important. Let me write it again, this time in italics. Reviewing software is often harder to do effectively than the act of writing it in the first place.

I believe code reviews hold incredible promise. There is no better way for us to learn than from each other.

I’ve struggled for years to come up with a solution to the code review problem. If you are on a team of software engineers, perhaps this isn’t a problem for you. Perhaps you are able to conduct thorough reviews on every single line of code in meetings and/or with sophisticated tools.

I have not been so lucky. For a large part of my career, I’ve worked as a solo software engineer on teams of electrical engineers. — If you think it’s difficult to conduct code reviews with software engineers, just try to get an electrical engineer to pour through thousands of lines of source code.

The best sustainable solution that I’ve been able to come up with is to architect the software to facilitate “targeted reviews” while also providing the complete source code to my teammates in an easy-to-access intranet-based folder. Relevant sidenote: Distributed version control repositories (e.g. Git, Mercurial) are great for publishing source code in intranet folders because the tools make it easy to automate the updating of external locations with a single shell script.

Doing all of this supports the targeted reviews but it often requires PowerPoint “conversation starters” to introduce key algorithms before ever looking the actual code. When done right, coordinating brief meetings with the relevant parties can be straightforward.

Overall success of this approach hinges on the act of being transparent with every bit of produced source code and supporting material; all organized in a way that is discoverable to the reviewers. The good news is this form of transparency has an added benefit of building credibility.

When you are on a team, the source code and opportunities to criticize the codebase should always be available to everyone on the team anyways. The benefit is in actively soliciting feedback.