Code Read Play

In my programming infancy I learned that Hungarian notation was an outdated practice, that was useful way back when data types weren’t strictly enforced by the compiler. You needed little helper characters to help communicate the datatype of the variable, how it was meant to be used. Boy everything was fragile and on the edge back then, it seems. 

Anyways, these were manifested as single letters preceding your variable name- p for pointer, f for float, b for bool. fTotalCost, bIsTrue. Mostly we don’t need this anymore, and it isn’t in common practice. But it impressed on me a sense that any labeling of a variable as its data type was awkward practice. Variables should now be filled with meaning, meaning of the abstraction of what they represent.

Today I had a revelation that, sometimes, the datatype itself is embedded in the meaning of the variable. I had a variable ‘cartType,’ which represented an enum value, but in this case it was coming in as a string through a javascript ajax call. For some reason renaming this variable to ‘cartTypeString’ felt clunky, but reasonable enough that I realized that I’m not (always) being lazy when my variable name has a data type listed in it. 

Usually, in having a discussion about someone else’s code, we are talking about design. It’s nice to be on this side of the conversation, the side that doesn’t have to manage the code. From over here, you can see ideal architectures without having to worry about how painful it will be to code. When you are tasked with facing on the code head to head, or have already began building the walls, suddenly you have quite a bias about the design.

There is a tendency to try to make things small.

A small project, it is easy to see all the moving parts from the outset. Need a little of this, that module, this piece. We’ve done most of these things before, I can picture most of this project in my head from the start.

On a big project, it becomes daunting. There is this strong desire to make it small, as if by willing the pieces to be manageable they will be. These are the modules we need. That one will take a week probably, that one two weeks. That part shouldn’t be that bad. It’s just a few pieces, then put them together.

The trouble is that every line of code is one line of code. Just because you need 10,000 of them instead of 1,000 doesn’t mean they can get done any faster. Functionally, you need all the logic, all the branching flows, all the minute details. Every variable must be assigned. By the end of a small or a big project, you will have to grok every if statement, every for loop, at the same level of detail. You don’t have to understand the details of the big pieces at any less granularity just because there are many of them, just because you don’t have time for all that detail.

It’s a strange sensation going into adding a new feature to legacy code - seeing a big block of code that is complex and scary. I need to change one small piece of functionality, but I need to wade through a huge set of classes to hunt down the change needed in the code. By the end, I will probably understand all of that code. I get that concept now, but I still resist it. I want to understand as little as possible to make the change. But inevitably, by the end, I’ve spent a good length of time getting into and debugging the code, and usually have a full, detailed understanding of it.

So just go in with that mentality! Go into a huge block of code and say “I need to understand this to a great amount of detail,” and just accept it. It’s ok. It takes a while, it takes patience. But you’re going to get there anyways, you’ll spend more time trying to work out why a messy fast fix breaks other things than you would have just getting a good handle on the code in the first place.

This is a similar sensation to learning a piece of piano music. I look at the full piece of music and feel a little overwhelmed. I am awed thinking that by the time I am done with these three pages of music, I will have really dug down into each note and have a detailed and loving grasp of every little section, every measure, every rest, how they all fit together. When you see the end product, it is a complete piece of music. You may not hear some little moves the left hand is making when the right hand is playing out a melody. But I worked hard on that section, grew a relationship with it. It may be three pages of music, I may sight read it in a few minutes. But over the next few months, to really learn a piece of music and to play it fluently, you will get down into the details. Just go with it! At the end, the relationship and experience you have with the music is greater than the sound that is played, the emotion that is expressed. Music is not just something to be played for others, it is really a very personal experience.

I just got an infuriating response from a fellow developer. I just saw Steve Jobs (which I really enjoyed,) and envy his wit - his ability to see the flaw in the moment, in the discussion. Of course, in his reality distortion field he can also kind of create flaws in your argument, I don’t necessarily want that, though it sure would be useful.

Anyways, I need a moment to process things like this. I asked the developer about some code he had written. I had a sense for what was going on, but it was big, and there were a lot of moving parts, so I wanted his insight, anything he remembered about how this works.

He said “Yeah, that part was really tricky. It’s whatever the code is doing.”

Well obviously the code is doing what the code is doing. This kind of translated to me, “Just read the code, why are you asking me.” And taken a defensive step further “You’re being lazy.” Or worse, “If you were a good programmer, you could just see what was going on by reading the code, and wouldn’t need to ask me.” Well, a comment in the code would have been nice. I can see what the code is doing in the places I’m looking - but there are thousands of lines across many files! I could assume that my view of the code I’m looking at is the boundaries of the entire functionality. I could assume I’m a great coder, and so don’t need outside input, don’t need to get a feel for other developers’ intentions, but this is obviously short sighted. This is actually quite similar to my rant about comments actually.

When my sister was planning her wedding, my dad refused to give her a budget. He thought they are all reasonable, they can work it out, talk through every item, every expense, work out what feels reasonable - what is the point of an arbitrary upper limit? Perhaps he thought he could keep the cost lowest by closely monitoring and approving each expense. What ended up happening was that as the costs went up, every additional expense became a point of stress, both for my sister who wanted it, being anxious about debating another expense with my dad, and for my dad, who wanted to balance his daughter’s happiness with a reasonably priced wedding. Had he come up with a budget, he could have left it and not worried. Now the onus would be on my sister to manage her own expenses within that budget. A straightforward numbers challenge for her, without having to manage my dad’s feelings, and really nothing for my dad. Perhaps he had some additional wisdom here I have not yet learned, I should ask him.

Parkinson’s Law states that a project will fill the time budgeted for it. So if you give two months to a project that could actually get done in one day, it will take two months. This is absurd! It makes me angry.

Using an example of a single developer, there are two reasons I see this might happen. 

1. The developer explores alternatives, optimizes, and polishes with this extra time. Is this time completely wasted? The developer is engaged, he/she is learning, deepening understanding of the system, making the system work better, rooting out potential system issues. It seems this is a sound investment. Given that the final product will be higher quality, the developer will have more pride in the product. In addition, his/her knowledge and experience in this domain will be enhanced.

2. The worker slacks off and counts any time not required as free time. Sitting on a completed project for all the extra time, saying that the project is on schedule. This is basically dishonest. If this is true, you have a dishonest developer, and budgeting time for them isn’t going to save you much beyond this fundamental detriment. However if you are ACCUSING someone of this and they are basically honest, that will be a serious blow to morale. Actually, even if you accuse it and they are not honest, it will be a blow to morale. Bad news.

Many people seem to consider Parkinson’s Law true, even if they’re not aware of the term (which, by the way, was given in a satirical article written in 1955.) But generally, when I feel pressure to reel in an estimate I’ve made, I am just flustered. Why don’t you let me shoot for my own estimate, and if I’m done earlier, I’ll tell you it’s done early? Even after several projects where I’ve called completion early, the belief in Parkinson’s Law does not change, and I still feel its awkward pressure in planning projects. I suppose there is some benefit to a business to have accurate predictions, but it seems finishing earlier is always better than finding out it will take extra time, and if you’ve come up with working baselines based on over-budgeted estimates, then when they come in early you’re still clear, everyone can still be happy. Every time my estimates are reeled in, being viewed as longer than they should be, I simply feel maligned. This is particularly bothersome because almost all projects take longer than expected. Does assigning it an earlier due date change the time it actually takes? I doubt it.

Perhaps I have some business rules to learn, but it seems if you make a budget that works, and then are successful at meeting or doing better than the budget allows, you have a win, even if it turns out you may have been able to reduce the budget beforehand.

It also seems strange to me that a person or a company would maintain the same set of beliefs without trying anything new - “We must assign an earlier estimate, because that will make the project go faster.” And when the project is late, justifying the earlier action by saying “Good thing we pulled the estimate in earlier, or who knows how much later it would have been had we used the initial estimate!” At the very least, compare performance of projects subject to the compressing pressures of Parkinson’s Law with projects not subject to this pressure! That is - try a few projects where you allow the full estimates of those doing the work to be the budget, and see what happens. This will also help prevent the strange game of developers reporting a bloated estimate with the knowledge they’ll have to lower it in negotiations. Ick.

On my way to lunch, I had to walk around a conference room where some big, all day meeting is taking place. Our loud COO was loudly preaching something, I couldn’t make it out. But I had this sense that in the room, core decisions about the path of the company were being shaped.

I’m generally pretty condescending about how meetings with our COO is run, or many others. No agenda, willing to pursue various tangents. I can identify see topics and concepts that are pertinent to a given meeting, and I have a very sensitive sensor for when we get off topic. So I often feel like my time isn’t being effectively used when sitting in meetings, since we will go down various tangents that don’t relate to me or my domain.

Still, in this case, I felt like the meeting happening in there was important, and perhaps in meetings like this, the exploratory, free form meeting style more appropriate. Discovering the course to set for the company is more nebulous that the particular logic and logistics of software development.

There is certainly an element of fear in being a software developer. The fear is not as much being discovered for not doing enough work, as being misunderstood for how much work there is to do. I feel I’m constantly arguing, justifying, bargaining to be understood, that programming is nebulous, that things that seem simple can be hard, and things that seem hard can be simple. 

I do bask in the things that are easy that seem hard. I take undue pride as a developer when there is this perception, feeling like I am a master of my craft, feeling very productive. I guess I should enjoy it where I can.

The converse is much more painful. When things are hard but seem simple, all of a sudden I have to start to make metaphors, provide explanations, give a presentation about how programming works in this context, without getting into full detail about how to write a program.

Today I had a presentation showing some front end stuff. I was enthusiastic going into it because it was “simple but seems hard”, I knew it was going to have a positive reaction - it was a lot of content for a moderate amount of work. And it went well, people were impressed. But then, leaving the meeting, I had a sense of horror. Next up is dealing with data, dealing with internal bugs, small ripples on the surface that belie the great beast below. The next demo will have almost no visual changes, and I have a knowing fear that the thought will be “What has he done? What has changed? Oh, I guess he got a lot done last time and took a break.” I will be battling that perception, even if it is not explicitly stated. There are a few things that would save me from this fate. 

First, smoke and mirrors. Make some major unnecessary visual changes to reflect the great work I’ve done in a medium that can be understood by non-programmers. This isn’t productive, and frankly, it’s dishonest. Or skewed honesty. Also, it’d be strange that I made some visual changes in places they were not called for. But at least I’d seem productive.

Second, salesmanship. If I had a mastery for metaphors, for explanation, for selling, I could effectively sell that what I do takes time, and that great changes are taking place beneath the surface. I could be better at this, but this is a lifelong skill, I’m working on it. But even this requires some of the third thing:

Recently, I was working on a project with someone, I’ll call her Sue. This person was decent, good at what they did, friendly, easy to talk to. For reasons I won’t get into, this person had to be taken off this project, and in her place, Betty was assigned the same task.

Betty was awesome. I didn’t even realize what a difference a different personality would make. She responded consistently, and pretty much daily (it was a remote project.) She was enthusiastic, and the communication felt clear and effective, her results showed we shared the same understanding of our communication. Her enthusiasm and consistency inspired me, and I was probably twice as effective, and I like to think my extra effort inspired her to be more effective. Sue - not good to work with. Betsy - good to work with.

I was rather astounded at this change, at what a big difference this made. There are usually so many factors changed between projects that I can’t really compare this human element precisely - each project is different, so it’s hard to gauge the difference of those you work with separately from the rest of the factors involved in the project. In this case, the person was the only change, and it was amazing!

This got me thinking - having someone who is good to work with is probably the most important thing. It promotes satisfaction, collaboration, just good work virtues. What makes someone good to work with? How good they are at what they do is part of it, but is only a small part! Someone who is a master is not necessarily good to work with! Easy to talk to is important, a master of their craft definitely helps, but being “good to work with” is actually a combination of traits. Among these are responsive, reliable, consistent. When Betty said she’d do something, she did. I began to count on her to follow through on her word, where with Sue I’d begun to dismiss her promises, understanding that she’d actually get done as she got done, not when she said. I was ok with that, but it was a drag, and more and more constrained the work.

I keep thinking about what makes someone good to work with, it’s an interesting and somewhat nebulous idea. But certainly the key here is that I’d rather work with someone consistent and reliable than someone who is an expert, but not consistent or reliable. I’d rather work with someone who communicates effectively than someone who is an expert, but does not listen well.

"It’s easy to write bad code.”

A simple observation my brother made the other day, but it got my wheels turning. Of course it is easy to write bad code. Maybe not code that is highly convoluted, incomprehensible in twisted, nonsense logic, that may be easy for an intern, but is tricky once you have a good handle on standard coding practices. But good old fashioned, seat of your pants, bad code, it’s easy. It’s almost a relief to imagine writing code like this, just whatever comes out as you think of it, not worrying about dependencies and all the different angles that will or should come at your code.

The trouble is, bad code is on a spectrum. (Or perhaps, good code is on a spectrum.) Generally, the less “prepared” your code is for the code that comes later, the worse it is. Most times you have to go back and restructure your code to fit some new case, you’re weakening its integrity. There’s a difference here between this and “refactoring,” which implies a more dug in redesign, rethinking your existing architecture to fit these new cases.

This does not exclude one time use code - code that does exactly one specific thing, and can’t be utilized by any other code. If you’re writing the same functionality with some new code, but the old code is so specific that you don’t even want to touch it to accommodate this variation, then I would wager that old code is pretty bad.

But you can’t consider all possible angles that you’ll need to come at your code with until you start writing. It is an essential programming skill to be able to think ahead, to be able to consider the possible futures of your code usage, and to structure it accordingly. A distinct sign of coder expertise is largely just from experience - the ability to see what will make your code more rigid, the trade-offs of different paths and different designs, how to make it the most flexible, while keeping its power intact. Usually this comes down to modularity.

No matter how you plan, though, no matter what your experience, there are surprises ahead. If you could master the art of coding, it would be boring, so this is a good thing. Sitting down to write bad code is nice to start, because you are free from worry, writing whatever, seeing your results. But bad code does not age well, and if you need to make any distance, this will come back and crush you. The glory of good code is how it keeps on ticking, thousands of lines in. But to write good code, you have to worry about making sure it is good as you go. But it is not useful to worry too much. You can’t think about the all code that will be, and all the possible ramifications of design decisions. You have to strike a balance, deciding at some point to dive in despite your incomplete knowledge, to have courage that your attempt to write flexible and maintainable code will be the best you can make. It is important to be confident, but humble, and ready to learn and adapt. 

From ​Code Complete

It’s natural to assume that defects are distributed evenly throughout your source code. If you have an average of 10 defects per 1000 lines of code, you might assume that you’ll have one defect in a class that contains 100 lines of code. This is a natural assumption, but it’s wrong.

Most errors tend to be concentrated in a few highly defective routines. Here is a general relationship between errors and code:

Eighty percent of the errors are found in 20 percent of a project’s classes or routines (Endres 1975, Gremillion 1984, Boehm 1987b, Shull et all 2002)

Fifty percent of the errors are found in 5 percent of a project’s classes (Jones 2000)

These relationships might not seem so important until you recognize a few corollaries.

First, 20% of a project’s routines contribute 80% of the cost of development (Boehm 1987b). That doesn’t necessarily mean that the 20% that cost the most are the same as the 20% with the most defects, but it’s pretty suggestive.

Second, regardless of the exact proportion of the cost contributed by highly defective routines, highly defective routines are extremely expensive. In a classic study in the 1960s, IBM performed an analysis of its OS/360 operating system and found that errors were not distributed evenly across all routines but were concentrated into a few. Those error-prone routines were found to be “the most expensive entities in programming” (Jones 1986a). They contained as many as 50 defects per 1000 lines of code, and fixing them often cost 10 times what it took to develop the whole system. (The costs included customer support and in-the-field maintenance.)

One reason I love programming is the many tiers of thought involved, and how much programming you can do away from the computer.

From the top - you can think about programming from a requirements perspective. Anybody can do this! And you can play around with these kinds of thoughts wherever you go. What would you like this program to do? For example, in google keep - it’d be nice if in the checklists, you could nest items under other items. What else would be useful here? You are basically thinking about requirements, imagining a possible reality. Let creativity run loose, think about what might be nice. This is programming.

Next down is some design work, thinking about modules, thinking in big, abstract concepts. We need an actor who can handle these things, another to handle those things. This part is pretty cool, in thinking of abstractions, you are dealing with really powerful entities without limit, and because you’re just sketching it out, you can swing these powerful entities however you wish, without limitation, without the mass of actually putting them together - just imagining the powerful pieces that could exist to make a feature possible. This is also fun to think about, plan out.

There are a few tiers of design, you break down the modules into smaller modules, to no end. Again, this can be done away from the computer.

At the lowest level, you are actually programming out the statements to make the code work. This is fun too, but often not necessarily something you can think about while you’re away. Particular tricky challenges of navigating data structures can be fun mind puzzles, but for the most part this is in the moment, line to line, raw writing.

When you are writing a feature, you usually start from the top and work down. This is why this is generally more fun - you generate a vision and all the pieces are building towards that vision. Debugging is different, often less fun - you are starting from the bottom, looking at the code, and building up the tiers in your mind. Kind of like making a map of a building by feeling around in the dark. But this is satisfying in exercising your mastery of code, your ability to reconstruct. 

Writing a new feature, you can do largely away from the computer. Play with the ideas, construct and revise. Debugging is largely confined to direct investigation of existing code, and requires strict review.

Here is a self indulgent mind dump.

I expect to have a little meta reflection on blogging here and there. I haven’t written here for a while, and have been considering why.

I started this as a personal record, a place to expand upon thoughts. Like a journal. But being public obviously colors it, and I believe the way it colors it is beneficial, it changes the way I process my thoughts - it adds focus, adds polish, and adds a little bit of self consciousness that helps ground me in reality.

I feel I get into states of reflection, times when I am programming a lot and thinking about it a lot, thinking critically, thinking philosophically. I decided I wouldn’t write when I am not feeling moved to write, and would wait until I was in the right state of mind again, because it probably wouldn’t be too long. Yet it’s been a couple weeks now, and I do want to commit writing more than that, even if my mind is not in the right spot. And perhaps it is just coming around now. Or maybe I’m just feeling pressure to remain vigilant. Or some of both.

Part of what impedes me from writing is the sense of focus of this particular blog. It is personal, and I named it “Code Read Play” to allow it to accommodate a wider spectrum of my interests - not just coding, but the reading I do, which is on more topics than coding (especially focused on parenting these days, as we’re expecting,) and “play”, being a double meaning referring to playing music and playing video games, both of which are a major part of my life and my identity. Yet I often feel obligated to keep this focused on coding, since that has been most of my writing so far. Obligated to what? I don’t know, a long term sense of continuity, the blog as a focused project. But screw that.

Part of not writing is also external pressures. Too much Hearthstone, too much procrastinating. When work is unsatisfying, or I have addictive distractions, I do less work, less practicing, less things that are important to me. When it comes to turn back to being productive, I need to take care of urgent, priority items that have become that way because of my unsatisfactory time management. From 7 Habits, I’d call writing in the blog a quadrant 2 activity - important but not urgent. It is one of the first things to go, and seeing it neglected is a big part of the distress that video games, or other procrastination / distractions end up causing. It is less, though, than neglecting regular piano practice, and much less than neglecting work.

I feel similarly to the shortcoming of effort I invest in completing Tumbleweed Express, which we are hoping to release in March. I could do so much more here. I partly want to shut down playing video games for a bit, take a break, allow these other things to flourish. When I’ve done this in the past, I’ve felt really good about it, and been productive, and had a peace of mind in being on top of all the things the ideal Ben would spend his time on. But “Not yet” I say these days. “Maybe next week. I just need a little more fun.” This might be tied to the coming of winter, the madness of the holiday season, and the getting used to the oppressiveness of the winter cold. Or perhaps not. In any case, moving forward.

In code, switches are preferable to if/elseif/else statements. I didn’t understand the reasoning for switches for a while, a whole mechanic for doing the same thing as you could do with if/elseif, but more constrained. Later I learned switches were basically masking a “goto” statement, and thought they were just a vestigial remnant in the evolution of programming languages.

More recently though, a revelation - if I see somebody’s switch statement, I know exactly how it works. The readability is extremely strong. The constraints of a switch suddenly become its greatest strength.

I was looking through some of my old code, and saw a 4 or 5 item if/elseif statement that looked like it was evaluating different states of the same variable. I thought “Why didn’t I just use a switch here? Silly Ben.” But, not certain, I had to go through each condition to identify that there was, in fact, one condition that was more complex than what could be handled by a switch statement- a confluence of variables to evaluate. Ahh, this is why I didn’t make it a switch. But suddenly it highlighted the strength of switches - if you look at a switch, you know what’s going on immediately. There is a certain satisfaction in that immediate transmission of knowledge about a large chunk of code that is comforting and powerful. 

When someone says “If your code is good, you don’t need comments,” I get angry. I wish I didn’t, I try not to get angry as a rule. More recently, someone defended someone else’s code at work saying “Oh their code is really clean and not hard to understand, it’s not a big deal that they never comment.” (Also implying that if you’re having trouble understanding their code, you must not be very smart. Grr.)

I’m reminded of a Calvin and Hobbes comic:

Yes, your code is clear. Clearly, you are hammering nails into the coffee table. Can I change your code? It seems to me that we don’t need those nails in the coffee table, but I can’t tell from your perfect, clean, easy to understand code if it is ok for me to remove the nails from the coffee table. Why are they there, what are they doing? Are they a fix to a bug? Are they solving a very complex problem I’m not aware of in an elegant way? Is this whole class tied in to a module in some way that isn’t obvious from the references I can piece together from the IDE?

Code without comments often turns into a crime scene, and exaggerate my role of detective (a major part of being a programmer.) Except it’s very nearly malicious - it’s not that you wanted me to be in the dark, piecing together the clues. You were writing something that made sense to you, you wanted to build a working feature, a solid system, and thought if written clearly, its intent would be obvious. Well it’s not. Some pieces are easier to put together than others, but I’d say it’s near impossible to know which places will be difficult to understand, and which places will be straightforward, so the best practice is to have a habit of commenting everything well.

Somewhere I read, in regards to coding, that if you think people might not understand something, they definitely won’t. If you think you’re being clever, it will be incomprehensible. The justice here is skewed - usually those who suffer are not those who wrote the code.

Just like how TDD feels like overkill at the start of a project or feature, comments can also feel like they are not necessary. “Look, I just have a couple functions, a simple linear path. You can see everything that’s happening on one screen.” Before you know it, there will be many paths, many permutations, the simple feature will almost always grow into something with many appendages and secrets. When you’re working on it, you can usually keep these all in your head, or you can put a function out of your head for the most part because it’s doing what you know it’s doing. Maybe it’s well named, so it’s function is clear. But the “why” is fragile. When you come back in a year, it might be clear WHAT that function is doing, but WHY it is doing it, or why it is doing it this particular way, may remain a mystery until you change it and break the system, and everyone suffers.

And no matter how much you can remember, this is particularly heinous when the feature grows to encompass many pieces, many threads, many different moving parts. Programmers pride themselves on being able to keep massive systems in their heads. And it’s fun to be able to juggle this way. But it is much more painful to build up a confluence of code again, trying to retain each piece as you fit it into the puzzle. Comments don’t solve the problem, but at least they provide some guideposts to help put the pieces back together, to explain why you are hammering nails into the coffee table. 

From Coders At Work, interview with Peter Norvig:

Seibel: So is there any essential skill needed to be a good programmer? Different domains obviously have different requirements but ultimately is there some commonality to writing code regardless of the domain?