Make pretty stuff with fire

Originally posted at: https://www.codementor.io/blog/code-review-best-practice-6q5slpm2e0

Programming is often a team effort for introverts. When working as a developer, you will run into decisions other developers have made that you consider mistakes.

It could be a data structure designed with three tightly bound tables. It could be a massive REST API managing all the company’s requests with obsolete technology you need to extend or replace. It could include delicate, untested code that when modified, is likely to cause both personal and technical explosion.

I have built systems that contained all of these flaws, or worked with the (sometimes catastrophic) results. Working with and learning from other programmers is simply easier when you can critique their code effectively without offending them.

Typical Code Review Process

The first step in almost any writing is to 1) write something, 2) have a group of your peers read through it, and 3) adjust to their commentary.

The importance of peer review is mirrored in the fine arts, where feedback on the semantics of your decisions is a significant part of any class. When learning to program, however, you generally receive a series of close-ended problems sized for individual consumption, and peer review of your code is rare. This did not prepare most of us for a professional life in programming.

Reading the code others have written, understanding it, and providing constructive criticism is a subtle skill. Adding to this difficulty, the individuals being critiqued are often introverts. Thus, when I am reading code written by a student or someone on my team, I have three primary concerns:

Team Dynamics: how do I improve my working relationship with this person and their code?

Code Standards: how does this code conform to how it should look?

Reusability/Extensibility: how easily/effectively can this code be expanded upon, maintained, and rebuilt in the future?

Team Dynamics

Team dynamics are important in software development because nobody can know everything. A software development team usually consists of developers with experience and skills enabling them to build approximately the same things.

Most software teams that I have worked on are culturally diverse. Once, my Indian boss told me, “Where I grew up, if you weren’t in the top 5% by the time you were 12, you were screwed.” Thus, as a wide variety of experiences leads to different communication styles, communication and soft skills are an important part of a developer’s skill set.

Soft Skills and Emotional Intelligence

Sometime in the 60’s or 70’s the US Army coined the term ‘soft skills.’ Now, often referred to as ‘Emotional Intelligence,’ (for further reading, the work of Daniel Goleman is fairly approachable) these skills are different from raw, memorized knowledge.

Programming consists of many ‘hard skills’ (e.g. C driver programming, MongoDB querying, and Apache server administration) — most of them are fairly ephemeral in comparison to a career. Anyone can copy JavaScript off the Internet and make a flashing button.

Convincing someone their flashing button is poorly constructed or aesthetically ugly is often more difficult. Soft skills are important in building a consensus motivating forward progression, and maintaining that consensus regarding forward progression. And the easiest, most effective way I have found to convince people to move forward is this: say something nice first.

Say Something Nice First

O’Reilly once assembled a book called, Beautiful Code, and I can’t remember many people in the book citing their own code for samples.

This means if you say something nice to somebody about their code, it may be the first nice thing they’ve ever heard about it. When you start out with, “Wow, this solves problem X very elegantly, right here,” you are building a little goodwill within your team. Also, if you have to look hard for this positive point, you’ve learned something. Often a comparatively awkward approach merely appears that way because it has an entirely different set of priorities and steps. In addition, when an approach looks ineffective to me, when I look for something worth salvaging, I end up making a specific list of issues within the code.

Be Specific in Your Commentary and Criticism

Speaking in very specific terms about awkward code is an effective way to help someone improve it, as well as learn from each other. If you look at the classic FizzBuzz post at Coding Horror, you will see that there are a thousand ways to make even the simplest program go, in all sorts of languages. Here are two pseudocode functions for finding the last day of a month:

Date returnLastDayIterative(DateTime dayIn): Date myDate = dayIn.date while (myDate.month < dayIn.month): myDate.dateAdd (1 day) Return myDate.day.dateAdd(-1 second) Date ldy(DateTime i): Date m = i.date If m.dayOfMonth > 28: m = m - 3 m.month = m.Month + 1 m.day = 1 Return m.dateAdd(-1 second)

What are the good and bad things you see about each?

Algorithm 1 is linear; it’s a single for-loop in code, doesn’t have much logic, and gets the right answer every time. It’s also cross-calendar compatible for non-Gregorian calendars.

Algorithm 2 is probably more efficient computationally, but depends on months being of uniform size within 3 days (Mars or Jupiter months might be longer) and requires two library functions (month_add and date_subtract).

Both find a solution. On balance, since date-time functions can be heavy when applied to large datasets, I personally prefer algorithm 2 for its linear performance results. Semantically, these are simple functions but if I had to maintain one, I’d probably prefer to rewrite the first function over the second. To engender this kind of focused, productive communication, what will often help is code standards.

Code Standards

Not every team has formal code standards (this is an understatement).

The default standard for many teams is: “This is what manager X of programmer Y accepted as gold code on release day.”

But when you are looking at someone’s code and asking them to modify something in a way that requires their effort, code standards help. Most of the time, code standards are about things you don’t want to care about so you can focus on what matters more. Rather than worrying about whether each file is indented with spaces or tabs, you can focus on not dereferencing that NULL pointer.

Code standards will be very different for different environments, though.

When I tested internal loan software at Wells Fargo, we had hundreds of end-to-end tests to run before putting a release on staging servers. In a tiny startup, though, your flagship product may have only a smattering of end-to-end testing (or none at all) that you run once before release. Or, more appropriately, a selective battery of unit tests run by Jeeves, TeamCity, or whatever tool before auto-migration, and a small set of well-considered hand-tests.

Code Standards Will Vary By Environment

Coding standards will change per environment, language, company, end-use, and testing requirements, so a discussion of which standard to use is important and can make communication clearer.

“Hey, I see you used a couple variables here that were declared inline. Do you think we should do that, or declare them at the top of the function? It seems it would be easier to read that way, and agrees with [Agreed Upon Convention X].”

But remember, this will change depending on the situation. When you write Java, it is a completely different animal from when you write SQL.

My team once hired a developer whose experience was extensive in Java but not Python — our primary language. We handed them a standard code-sample request. Instead of the fairly simplistic Django – Python – Postgres result we expected, we received something built with Spring. There were interfaces, and abstractions, and a factory or two.

We examined it closely, because it was…baroque to us (well written Java is almost always going to look baroque to a Python programmer). Java programmers are trained to be relentlessly abstract, so their code is reusable in a wide variety of circumstances.

When you critique a (nowadays, probably logically generated) SQL block, in direct opposition, you want it to be simple.

“Can I read this, run it on a server, and know exactlywhat it does?”

If I see a SQL schema with extra layers to it, or an SQL query nesting arrays in a table, my instinctive response is to remove the complexity. This is directly different from standard Java protocols; primarily for environmental considerations.

Watch for What’s Inappropriate in a Specific Language

A simple JSON block or SQL query can cause a tremendous number of problems. If you think of all programming in state-based terms (almost all programs can be represented as Finite State Machines) the inputs and outputs that come from any program will change the state of all programs and users interacting with it.

Thus, the environment you are working within is extremely important to understand when you look at any code chunk. If you look at someone’s code, some of the easiest/most important questions to answer quickly are, “What are the inputs and outputs, and how did they change?”

Traditional database design started with hand-generated forms and reports representing data, and modern programming technique can learn from this approach. Looking at JSON input block A and comparing it to JSON output block B should allow you to ask important questions of your fellow programmer. Likewise with a series of SQL queries pointing at the tables in question.

Check if the Code Can be Easily Maintained

When you start to talk about environments and tables, reusability and maintainability become fundamentally important. Maintainability presupposes success.

“We will need to be ready to upgrade this code eight months from now because it will be useful enough to keep us all employed,” is quite a confident statement. Telling someone that you believe their code is good enough for someone to pay for it not just today, but tomorrow and next month too is a massive compliment. I suggest saying something along those lines to them, right before you say, “But I can’t tell how or why it does what it does because there is not a single comment inside.”

When you review code, you are reviewing it not just to learn and improve your skills, but to help the creator of said code improve your/their ability to change it later.

Reusability

Would I want to be responsible for modifications to this code?

A great place to start making code more flexible later is in your code standards.

“This would be more readable if your variable names were not all variations of ‘foo1,’ ‘foo2,’ ‘bar1,’ and ‘barA4X,'” is a very good comment that code standards will help with.

Modifying or understanding large chunks of code is much easier when you follow consistent formatting and naming rules, as well as syntactic conventions.

I may not have written a bunch of Perl, but I certainly can cook up regular expressions that look like it, given time to brush the rust off. However, I have found writing three lines of code that do what one line of Perl-code-like regular expressions could do can save me a day of, “Whichever idiot let me do this eight months ago should be keelhauled,” self-recrimination.

Pointing this out to someone, or at least asking them to write five lines of documentation explaining their brilliant line noise can be enlightening for both of you. And once you’re done with the simple stuff in code standards, I strongly suggest looking at the dependencies.

Reinventing the Wheel vs. Inheriting Unreliable Libraries

I don’t particularly enjoy writing code. It’s always buggy, and doesn’t do exactly what I want. It needs to be rewritten repeatedly to handle special cases or additional inputs. Quite often, someone has run into one of my dumb problems and solved it in a way smarter than I am able to:

Conceptualize quickly without effort, and

Implement without a ton of bugs in a reasonable amount of time.

Thus, I don’t write everything in machine language. Or hand-laser wafers to get the exact transistor chains I need onto a chip. Or, sometimes, write as much Python.

Sometimes, however, I pick risky libraries. Or pick libraries that don’t do what is expected, or have insufficient testing for my purposes. When I look at code other people have written, I want to know the libraries and external chunks they’re working with to see if they are appropriate to the task at hand. It all boils down to is the implementer aware of the tradeoffs involved in using the selected references?

Generalizing Code

Expansion vs. Refactoring for Compression

After you understand what a chunk of code does and what it’s built with, the fun part comes in: where can this go?

This can actually be pretty inspiring for both of you. If the code you’re reviewing has done its job properly, you can look at it with an eye for where it can solve other problems, and be generalized. For example, should someone write a function that solves the small problem of setting a default date based upon a date-based input? You can look at the kinds of defaults a system might want: next week, next month, last quarter, etc.

Conclusion

Soft skills can make the difference between shipping a product and your source dissolving into code fiefdoms. Without a doubt, when you are working with a team, you will need to look through their code.

I have found that as I have become more effective at critiquing others’ code more politely, the software I have produced has become better. The primary ways I try to support the teams I work with in critiquing their code are through improving the team dynamics, pushing for more consistent code, and trying to help developers produce code as reusable as possible.

History-Light in PDX, an installation proposal

Economies are the stories of people.  Millions of people. Oregon has long been a place where things were made, where raw and processed resources came from, where people worked to create, acquire, and innovate.  Portland’s economics reflect this, and this work aims to interpret its place in the Northwest and the world.

  Fort Vancouver was a trading center.  Furs were collected, to be shipped to Guangzhou in the Far East. Thereafter a gold rush came.  The Oregon Trail. A state that started as forests to be hunted in grew to a source of lumber, and fish.  Then beef, and electricity, and ships. Contemporary Oregon produces microprocessors and machine parts. A hospital employs the most people in the state.

  This installation attempts to coalesce the experiences and lives of millions of people doing thousands of jobs over 150 years into a cohesive visualized history.

  The individually created installed glass pieces will be divided among designs representing economic factors and industries significant in Oregon’s history. Those factors include:

Forestry

Fishing

Food service

Greenhouse agriculture

Field agriculture

Cattle agriculture

Electrical power production

Medicine

Software

Semiconductor Technology

Education

Athleticism / athletic design

Machinery production

Ship building

Mining

Mineral production

Tourism

Fur trading

Beer

  Each of these forces has waxed and waned in importance through the history of Oregon. At the beginning of Oregon’s statehood trading and mining were the lynchpins of commerce. Over the course of time, these forces were supplanted. For significant periods, logging, fishing and agriculture were the primary forces driving the state’s economy. This has evolved into a contemporary Oregonian economy, which combines almost all of these industries and forces.

  These individual factors will have a plate design with a diffused LED matrix behind it, bringing it subtly to life with softly moving light. The installation will tell the story of Oregon and the Northwest once an hour, by slowly cycling between the brightness of various influences on everyday life. From its beginnings in the fur trade and gold rush to its production of world distributed semiconductors.

  Example Designs:

  Field agriculture: yellow lined glass platters with a slow, sussurating play of light mimicking the wind playing through wheat in the summer sun

  Fishing: a plate showing the occasional glinting of fish in a river, silver on blue

  Medicine: pure white platters with two slowly pulsing red heartbeats, one larger and one smaller, representing a mother and child

  Athletic Design: a lined plate with staggered lights, representing runners on starting blocks, that course together and reach an endpoint

 Brewing: the bubbling of fermenting grains projected on a platter, describing a dark Amber carboy in action.

 Electronics: a green and yellow lined work resembling a PCB, with occasional dots of white light representing data flow.

  Installation technical overview:

The 60’ x 60’ areas will each have a 40’ x 40’ offset grid of objects suspended in a plane above the ground plane. Each object will consist of a hand blown glass platter, an LED screen with an Arduino microcontroller behind this platter, and a diffuser between platter and screen.

Each microcontroller will be networked to a controlling program telling it which light pattern to run and how bright to make that pattern.

The microcontrollers will send a REST API call to a Django server once every ten seconds, and the Django server will tell it a: which numeric ID has been assigned to it, and b: which configured display set to use.  It is assumed that extensive management and programming will go into each display’s setup.

The average programmer starts their career with an education in the abstract nature of building software.  Arrays, linked lists, pointers, operating systems programming, data structures, and other technical topics.  Fundamental pieces for creating effective, efficient programs.  But if you want to stay employed, or to make things that millions of people can use, or just build something to show your friends, it is more effective to keep something else in the forefront of your mind. Like Google and Apple before you.

Google’s success was quiet, at first. In the late nineties, I started hearing about their search engine on Slashdot. In a world where Fetch and Gopher had been useful less than five years before, and Yahoo! sold the top results, I could type something into a text box and Find It. Wikipedia wasn’t that big then, either, so being able to say, “Huh, I wonder how long it takes to soft boil an egg,” and finding ten discussions about boiling eggs was revolutionary. And Exactly What I (and other people, apparently) wanted.

Computers don’t naturally do what anybody wants. We’re analog. We have thousands of disparate, unconnected inputs every minute. We then sift through all of them to assemble a central stream of consciousness, and continuously output a long series of motions with variation in direction and intensity no computer can yet match. No computer probably ever will match.(2) Given this constant input, and all the control over it other people attempt to gain, any tool that makes our lives simpler is welcome. Apple interfaces have worked to provide that since the Macintosh. It’s a simple white box with easy to push buttons. As long as you don’t throw around the plastic box, it is hard to break. It just does what it says it will do; sometimes more, but never less and very rarely is it frustrating because it makes doing something that you think should be easy hard.

These are excellent examples of software that focuses on People.

As an engineer(3), my focus has been on writing software that made technical tasks easier for people. I work to design databases that are simple to use because of their clean, logical, effectively connected organization. I work to name my variables and document my code well, so that the next programmer(4) doesn’t curse my name. I ask lots of questions about how the people I’m working with want my code to talk to theirs. I try things I think are stupid, because they probably aren’t stupid if you didn’t write the code(5).

It’s funny that I meet so few programmers who have read, “Beautiful Code.” Because while it is a book almost entirely consistent of esoteric examples, every one of them is pretty well documented. And each of them makes some sense as to why it was picked. And most of them are pretty…. Well, simple. Especially the ones where someone picked somebody else’s code. (the JUnit code stands out)

So my advice to you is to make your code as simple as possible, but with depth and flexibility under it. And aim for the same in your interfaces. And your documentation. And your life, when it comes down to it. Simplicity is the most complex thing to make.(6)

I can’t teach you any of that, I don’t think. But I can look at your code and trace the logic and perhaps dig into a bug or two, if you want. And tell you what I don’t understand; if I don’t understand it, you might want a comment or two – I can program in a lot of languages.

1 – Not ALL programming. There is definitely some programming out there that’s all about math. Kinda. It’s still about people, though, because people hate (and are naturally bad at) math and computers help do it. (Did you know Babbage really just wanted better logarithmic tables? ‘Fun’ fact.) 2 – Why bother? There are lots and lots of people, they’re pretty good at being people, and it would be really expensive to make one from component parts. I don’t understand the attraction. 3 – Sort of. It’s a long, complicated story and questionable definition. 4 – Most times, this next programmer is me. Making this what some would call, “Self Care.” 5 – “I’m the greatest sword fighter in the world.” “And you wrote the software.” “Yeah. That, too,” – Hiro Protagonist, who writes interfaces for himself. And Is Unemployed. (Snow Crash, Neal Stephenson) 6 – This is where I COULD go off on a glassblowing rant. I could talk about how hard it is to make a simple thin round cup by hand, like you can buy machine made at Ikea for about ten cents. I could go into how mastery of any material requires understanding of its limits and flexibility. How open-ended problems are the hardest problems, especially to make look right when if you touch THIS special tool to THAT particular area at the wrong time you’ve lost your chance at making perfection until you start again. How learning to make physical objects informed my perfectionism in code, and the massive pile of broken glass I have produced was totally worth it. I’d never do such a thing.

Glassblowers get some odd questions that are a little difficult to answer.  I personally got asked this by someone during my interview to blow glass on a cruise ship….  While I was demonstrating how completely un-hireable I was as a glassblower at the time.  So I’ve thought about it for a few years, and asked a physics professor, (who gave me a boilerplate, ‘because bubbles are round,’ answer) and now there are diagrams.

Let’s start with: they’re not.  They’re only MOSTLY round.  There’s only a little bit of a difference between mostly round and all round, though, fortunately.  So glass can LOOK round, even when it’s not completely round.  Let’s start with a diagram of what ‘high pressure air inside an enclosed space of regular pressure air’ looks like on a molecular level:

  The interior red arrows indicate denser / hotter atoms bouncing around inside the bubble.  There’s about (according to my rough calculations) 6.02 x 1022  atoms of air in that 1 square inch inside the hot glass.  These little atoms act like lots of tiny mosh pit residents trying to get out of the glass.  Therefore, they bang into any ‘edges’ in the walls pretty much equally, as long as gravity doesn’t make some of them hit harder.  Uncountable (to us non exacting types) tiny hammers making a round looking object through patient force.  Like this: (Note that when you look closely, it’s NOT ROUND, sadly)

The Surface tension of the glass resists the outward push of the air pressure differential, while gravity pulls the weight of the glass itself down.  The result is that a glassblower is required to continuously turn the glass in a circle to keep the glass more round; the force of the gravity needs to constantly affect the bubble itself in a uniform manner if possible.  So the closer to truly continuous uniform circular motion the glass gets, the more round the glass will stay.  This is a difficult thing to learn, and is one of the first problems a new glassblower encounters.

A free body diagram of the process looks like this.  The red arrows represent the more dense moshers pushing the bubble outwards, while the blue arrows represent the uh….  Plastic mesh fencing trying to hold them in.  I guess gravity would be the band, which everyone wants to be closer to.  So you try and put the whole crowd on a turntable.  Yeah.  This metaphor has gone too far.

  The diagram below shows all the forces as applied to a somewhat perfect bubble.  Everyone has a minutely different favorite shape for different types of bubbles for different purposes…..  But the glass is on center.  The surface tension is pushing in equally (partially, probably, due to marvering, which is a whole separate discussion) And the glassblower has kept the piece on center.  This one’s probably too round at the tip by a bit for certain applications, but you get the idea.

When this uniform circular motion is not achieved effectively, the wall thickness of the glass changes in unexpected ways, leading to the surface tension of the exterior being inconsistent around the edge of the glass.  This second pair of pictures shows the glass in a marginally less ideal diagram.  This second bubble diagram hasn’t been turned uniformly.  Therefore, there’s a thin spot towards the bottom.  Since the bubble blown into the glass will remain circular, the spot which is thinner will continue to thin out.  Which can lead to a cascading failure where the surface tension spirals towards being progressively more uneven with the wall thickness.

This thickness issue is important.  So important, I am led to a tangent:

Sean O’Neil ( http://www.studiomanufact.com/ ) once asked me what I thought the advantage of being a left-handed glassblower was.  All the tools in glassblowing are made for right handed people.  Heinlein even mentioned left-handed glassblowers disparagingly. (“First thing [the military placement officer] does is check whether there’s any need for left-handed glassblowers this week,” Starship Troopers)  The fine-detail manipulation of bits done in Venetian glass is done with the right hand, which makes it tougher.

I personally believe, however, that there are two.  Firstly, people who use their left hands for stuff are used to learning new tools twice.  Once the way everyone else does it and once with a tool designed for their 10% of the population.  Having learned to type with two separate layouts I found it made me more effective at both layouts in the end.  Generally, in my experience, cross training your brain is an effective means to the end of surpassing a previous limitation.

However, when attempting to make on-center and uniform objects using gravity my belief is that lefties have the advantage from the beginning.  This is because the hand that is working with and against the forces of gravity to keep a piece on-center is the left hand.  Silver lining in every cloud.

Here’s a picture of a pretty goblet bubble.  OOooooooooo aaaaaaaaahhhh…..  That became something pretty nice.  Anyways.  Thanks for reading.  Share this with your friends, please, if you think they’ll be interested, and feel free to ask for more explanations.  I like answering questions and talking to people.

  Dylan.