simplistic artEvery red-faced technical debate that I’ve ever gotten into has almost always devolved into one topic:  is this solution simple or is it complex?  And yet, there’s one alternative that we always forget about: simplism.  Simplism is simplicity’s evil twin, and it can be difficult to tell the two apart.  The difference between the two is that simplicity will grow up to be a successful adult who will make you proud, while simplism will grow up to be in jail, doing drugs, and always borrowing money from you.

Ok, so that analogy is a little bit hokey.  Let’s try looking at the dictionary definitions:

simple – easy to understand, deal with, use, etc.: a simple matter;simple tools.

simplistic – oversimplifying complex problems; making unrealistically simple judgments or analyses

When you do something simplistic, you are essentially sticking your head in the sand. You’re implementing a solution that meets the requirements of some problem that’s much simpler than the one you’re presently facing or will be facing in the future. And it’s always the latter part of the last sentence that gets you. Most people are smart enough to know when a solution doesn’t meet their present needs. But trying to find a solution that will be flexible enough to meet whatever random occurrence should come up in the future is tough.

Some people will tell you to stop right there. You don’t know what’s going to happen in the future, so don’t worry about it. But I think that the sign of truly elegant code is that it can be made to do all sorts of things its original author never dreamed of. There’s no need to contort it to do crazy things because it just works. And before you write that off as over-engineering, stop to think of the bigger picture. Remember: business requirements have a habit of changing suddenly in the most unforeseen ways. To get things done, sometimes you have to be willing to not get them done right this minute. As the Zen of Python says:

Now is better than never.
Although never is often better than right now.

So how do you keep things simple without making them simplistic?

I’ve found exactly one method that reliably makes software simpler without making it simplistic: make the software do less stuff. From a strictly technical standpoint, this is a surefire way to make software that is simple and not simplistic. Of course the business side will insist that you meet the requirements and then some. And they have good reason. I only said that this makes things simpler from a technical perspective. Technical simplicity might be business simplism.

But 9 times out of 10, there’s a way to satisfy both sides if they’re willing to compromise. There’s something to be said for the 90% solution. It does 90% of the things business people want and is 90% perfect for the programmers. The 10% you cut out might not sound like much, but if you cut out the right 10%, you’ve earned your salary along with one of your coworkers’.

So what’s the moral of this story? Before you decide on the solution that seems “simplest”, stop and think. Is it really simple, or is it simplistic?

How to have a side project

If there’s one part of a programmer’s professional development that is harder than it seems, it’s starting a side project. I, for instance, love to program. The funny thing is, that programming is the easiest part of programming (those of you who are true programmers will know what I mean). The hardest part is starting to program and finishing your work.

That said, I do have a few bits of advice for programmers who want to start a side project. If you follow my advice, you probably won’t write the next big thing, nor will you have a side project that will stand out particularly well on your resume. But you’ll probably write something that will make you a better programmer, and that’s the point, isn’t it?

Here’s what I’ve learned about starting a side project:

#1 – Have a good time

This is the first point on here for a reason. And I should hope it’s self explanatory. However, note that there are good reasons for making tradeoffs here. I’ll note them below, but there are some things that shouldn’t be tradeoffs. For instance, don’t make tradeoffs based on how it will look on your resume or what the latest and greatest technology is (not that either of these can’t be fun).

#2 – Learn something

I’ve known some programmers who live by the mantra “I’ll learn it later”. Here’s the problem: later never comes. You’re just going to have to accept the fact that you as a professional need to have some responsibility for your own development. Fortunately, a side project is just the way to take on that learning.

#3 – Make it timeless

Here’s where you may have to make tradeoffs in terms of fun. The most fun things are usually a hassle to maintain. For instance, suppose you write a new twitter client. I can guarantee you that at some point in time, the twitter people will change their API in such a way that will break your code. Granted, this isn’t a big deal if you put a lot of time into it. But that’s the problem: no matter what you do, there’s going to come a point in time in your life that you have something else to spend your time on or otherwise just won’t want to deal with your side project. That’s normal. What you want is something that you can come back to after that time is up.

This is part of the reason why I chose pysistence for my project. Aside from keeping up with language changes, it’s doubtful that functional data structures are ever going to change such that my code will break.

#4 – It doesn’t have to be code

I’d probably say that the blog you’re reading right now is my most rewarding side project. Don’t underestimate the value of doing things that aren’t coding. It’s fashionable to talk about how bad it is to be “all talk and no game”, but the fact of the matter is that reading and writing about programming helps you to solidify some of the ideas that may be forming in your head.

#5 – Make it something you’ll use

This is the last point, but that doesn’t mean it’s not important. If you write something fun, you’ll abandon it as soon as it stops being fun. If you write something useful, you’ll have a reason to keep coming back!

The Rolling Stones were wrong

The people that I work with must sometimes see me as selfish. And who can blame them? If an idea doesn’t excite me, I’m not on board with it. Don’t get me wrong. I understand that sometimes you have to do things you don’t want to do. And when one of those moments hits you, you just have to roll up your sleeves and do what needs to be done.

…but it’s surprising how rare those moments really are. I mean really, which do you find yourself saying more:

  1. “Man. I really want X, but I just can’t do that. There simply isn’t any way to avoid doing Y instead.”
  2. “I really need to get X done, but I keep procrastinating. I need to get my act together.”

buy it Judging by my highly scientific approach of recalling blog postings I’ve seen in the recent past and comments I’ve seen on Hacker News, I’d say that problem #2 is the far more prevalent problem. Now sometimes you do run into a situation where you have to deal with something bad to get something that overrides that badness. But at the end of the day, I don’t run into many moments where I just have to do something I don’t want to do. It just doesn’t happen that often.

Some of you probably still see this attitude as selfish, but I don’t think it is. You do need to focus on others in addition to yourself. But happiness isn’t a zero-sum game. Happiness is more like an infectious disease. A person who is excited will also make others excited. They’ll be giving their team their all. Likewise, a person who just isn’t happy can drag others down.

But in either situation, how often do you run into a person who is successful at something they’re not happy doing?

How to Write: A Programmer’s Guide

I love writing. I think I have talent in writing. But that doesn’t necessarily mean what I’m writing is good. To become a good writer, you need to put in work and experience. Here are some things I’ve learned along the way:

Practice makes perfect – It’s indisputable that great athletes like Michael Jordan and Wayne Gretzky have a lot of talent. But that doesn’t mean that they were able to go into the major leagues on their first try. Similarly, you might have talent, but it takes practice to unlock that talent. If you don’t have talent, you can still become good at writing. It just takes more time and patience. Blogs are perfect for this. Rest assured of one thing: if your writing sucks, nobody will read your blog. That’s actually a good thing because that means you can write all the stupid things you want and no one will read them until you get good at writing.

I know you’ve heard it a thousand times before. But it’s true – hard work pays off. If you want to be good, you have to practice, practice, practice. If you don’t love something, then don’t do it. -Ray Bradbury

Write because you want to – How many people have you met that “really needed to start blogging”? Don’t write because you think it’s good for your career or because programmers “need” to have a blog. I write about programming because I love writing and programming. If you love programming but not writing, then chances are your time is better spent writing code.

Love is easy, and I love writing. You can’t resist love. You get an idea, someone says something, and you’re in love. -Ray Bradbury

Just write it down – When you write something the first time, it will suck. Therefore, if it doesn’t suck at first, it hasn’t been written down.

Writing is no trouble: you just jot down ideas as they occur to you. The jotting is simplicity itself—it is the occurring which is difficult. -Stephen Leacock

Edit – In this sense, writing isn’t a whole lot different than coding. When you start coding something, the most important thing is just to start coding and not worry about it being perfect. But no code worth writing is perfect the first time around. You have to test it, break it, and make others read it to see if it’s clear. Writing for humans is no different. You must be as merciless in your writing as you are with your code.

I’m not a very good writer, but I’m an excellent rewriter -James Michener

The Wolf in Sheep’s Clothing

The idea of simplicity has been on my mind a lot recently. I have yet to meet a developer who doesn’t believe in it. So everyone believes in simplicity, shouldn’t we have a lot of simple code? Well, no. The other thing that every developer I’ve ever met agrees with is that there isn’t enough simple code out there. This implies a few possibilities:

  1. Programmers don’t believe in simplicity as much as they claim.
  2. Programmers don’t agree on what simplicity is.
  3. Programmers mistake other things for simplicity.

I ultimately think our situation is a combination of these three things. Numbers 1 and 2 are just the nature of the beast. Sure, everyone wants simple code, but let’s face it: deadlines can make that difficult. And the fact that very few people can define simplicity (and I don’t claim to be one of them) much less agree what it is makes it even harder.

But number 3 is the nasty one. I see it all the time. I’ve even done it myself (I know that’s probably hard for you guys to imagine ;). There’s one thing that I see people confusing with simplicity over and over again: expediency.

In the interest of full disclosure, I think it’s important to note that I haven’t found a good definition of simplicity in the context of software development. But I do know that whatever it is, it isn’t expediency.

Now, business types and “product people” love expediency. And who can blame them? Their job is to make sure a product gets created. Granted, I think they underestimate how important good code is to building a product, but that’s a different subject. Plus, I’m the first person to advocate working smarter rather than harder. I’m not necessarily saying expediency is bad.

The problem is when we confuse simplicity and expediency. Expedient solutions are easy to create. Truly simple solutions are easy to maintain and expand. Sometimes solutions areexpedient (easy to create) and simple (easy to maintain). But more often that not, you have to consider the tradeoffs. Do you create something to meet your immediate needs, or do you create something that will meet your future needs?

All I’m getting at is this: it would be really cool if people said “I don’t think we have time for a solution that simple.” rather than playing the simplicity card for themselves. After all, it would be the truth. And I think it would make sure that you aren’t confusing simplicity with expediency.

Myths about code comments

It seems to me getting good at writing comments is an under-appreciated part of a Programmer’s development. However, I feel that this is a part of programming that’s almost as important as writing code itself. So, here are some of the biggest misconception about comments:

Comments are free

This is an assumption that most of us make at one time or another. Comments aren’t actually executable code, therefore they aren’t maintenance costs, right? As it turns out, this isn’t true. When you update the code that the comment references, you usually have to update the comment as well.

Unfortunately, this myth is actually true most of the time. After enough time staring at a comment, it typically becomes “noise” that you tune out. Thus, comments have a nasty habit of not being up-to-date.

Comments make code more readable

This is by far the most pervasive myth that I’ve encountered. If anything, comments make code less readable. Nine times out of ten, I ignore comments unless I’m stumped. In fact, I’m tempted to make emacs hide all comments unless I explicitly expand them.

Comments don’t make code more readable. They are ways to compensate for code not being readable.

You should comment every function, method, class, and module

How many times have you seen docstrings like this?

def get_x(self): 
 This method gets x. 

This is about as close to being a canonical “bad comment” as you can get, and yet people who should know better still do it. Why? Because they feel that they should document every function or class. The reality is that documenting something that needs no documentation is universally a bad idea.

Code must always be “self documenting”

Most of the myths thus far have been of the “comments are a wholesome, healthy thing variety”. Don’t take this to mean that I feel that comments are bad. The reality of the situation is that the decision of whether to comment is just like most other decisions in programming: it’s about tradeoffs.

In most cases, comments should be viewed as code smells. But remember that code smells aren’t necessarily bad. They’re just hints that something might be bad. And sometimes, removing one code smell adds another one which may or may not be worse.

For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code’s readability suffers more when it’s overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.