Looking good, Billy Ray

After writing, reading, and reviewing code for many years, I thought I’d write about a few of the things I wish I’d known earlier. For experienced developers, none of this will be especially new or profound, but for less experienced developers, I think it may be helpful.

The first thing on my list is:

What the code looks like on the screen

When I hear things like “code is poetry”, I cringe because to me it sounds silly and kind of dramatic, but the underlying point resonates. I get it. Code really can be beautiful, both aesthetically and functionally. Beautiful in the way you might step back from something you’ve worked on and say “THAT is a thing of beauty.” You can just tell how much time and effort has been spent perfecting it.

Function flows from form. And for anything large in scale to function well, good form is a requirement. It’s the craft aspect of software development rather than than engineering aspect. It’s the part that demonstrates that you give a shit and take pride in your work. It indicates how aware you are of best practices and conventions. It’s a sign that tells others what you will be like to work with, how you communicate, and how detail-oriented you likely are. And ultimately, it significantly impacts how easy your code is to read, understand, maintain, and extend.

This is the list I’ve come up with so far…

You know my steez

I heard this song once and ever since, it pops into my head when I hear ‘Style’, which is the place to start. The ‘with ease’ part will come with time. The best thing to do is to use a style guide like this one. Almost all languages have one. If you’re doing something and are even a little unsure, just go look it up. Not only does using a guide tell you that you’re ‘doing it right,’ it defends you against someone questioning how you’ve done something in a code review. If you’re working solo, you might not think it’s such a big deal, but consistency across a large codebase is better for everyone who works on it. And if you’re working for a company or on a project, and there is a difference of opinion, you can at least start with a style that’s somewhat standard like this, and fork it if there are subtle differences your company wants to make. Using a service like Code climate is a great way to keep your team honest.

Totally spaced out

Spacing. This a big one for me. It still shocks and irks me when I see inconsistency in spacing. It’s a pretty easy thing to get right, but some don’t seem to either care or know how to format their code. I think that’s why it bugs me so much when I see it.

Take an extra few minutes and be sure everything has the right number of spaces and is indented correctly. Be sure your editor is using spaces and not tabs (unless that’s your intention). If you’ve used tabs for spaces in your editor it will look correct, but when it’s on Github or in someone else’s editor who has their editor configured properly, it won’t. And spacing applies not only to nesting and indentation, but also to the spacing of things on each line of code, and spacing between methods in a class.

And don’t forget about the newline character. Every file needs one. Read this to understand why. This look like a stop sign, doesn’t it? Don’t keep plowing through it.

Crowded classrooms

Class size. I think the same problems you find in a crowded classroom apply to class(model) size. It’s hard to pay attention, stay motivated, focussed and organized when the class has too many lines. You really don’t want to scroll down any more than you want to scroll to the right. Consider modules, concerns, namespaces, and anything else that makes the code adhere to the principle of single responsibility and separation of concerns. As with small methods, the more modular your classes, the more likely they will be easy to test, too.

Dry as a bone

DRY. Don’t repeat yourself. This one’s pretty easy, too, but I still see developers violating this rule all the time, and it’s usually out of laziness rather than ignorance. “How many times are you going to copy and paste that same thing before creating a helper?”, I’ll think.

The longer you’ve been at it, the more easily and frequently you are able to recognize opportunities for abstraction. And for me the DRY mantra goes further than avoiding repetition. It’s about the flip side of DRY — don’t do something that will cause you to repeat yourself. In other words, be generic when you can. Try to avoid the repeat-yourself-waiting-to-happen code before it happens. A method, class, or style name that’s to specialized may lead you to realize that you’ve done a bunch things in a bunch of places that are only slightly different. There’s a balance, though. You don’t want to over-engineer something, which is basically solving a problem you don’t have yet. I’m getting a little of course here, though. I brought this one up mainly because — visually — this is a pattern you can spot just by looking.

Bottom line is that it’s always worthwhile to take a few extra minutes and think it all the way through. Try to think ahead.

You’re so fancy

Fancy and clever. If you can be clever with clarity, then go for it. If not, don’t. If it’s not easy to read, you’ll probably forget what you meant in six months, anyway.

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?

It’s sometimes fun, I get it. But at least leave an explanation in case someone else has to deal with it.

Tersiness

Like truthiness. Can be a verb, too. I’ll sometimes refactor something and commit with a message of “Tersify”. The point here is to think twice about everything you write, and ask: is there a more concise way to do this? Can this thing be done with just one line instead of two? Is there a core function that already does exactly what I’m doing? Have I been doing it this way for so long that I’m unaware of what may have become a more standard practice? Do a search, ask a friend, put it on Stackoverflow. The fewer lines you have, the fewer lines there are to test, and the fewer bugs there are to find. Easier to read, as well.

John Hancock

Your signature, your calling card. Don’t forget that. It’s the first impression you’ll make on someone who’s trying to decide whether to hire you or not. Even without knowing what code does, and whether it actually works, it demonstrates with a fairly high degree of certainty how qualified you are. Someone with experience can look at your code and decide within a few minutes whether you know what you’re doing or not. You might not be able to fool them once they toss your code into the ‘maybe’ pile and look at it more closely, but that’s another topic entirely.

Finally, proficiency with this takes time. In fact, I know it takes time, years for some people. And for other it seems to never really sink in at all, even after having things pointed out over and over. I guess that’s just the IDGAF (kids text this to each other. I love it!) group. Don’t be in that group. Be in the group that knows there are known unknowns; styles, patterns, better ways to do things. I’m still in this group. Recognizing this is how you get better. The alternative is to be in the group of people for which this is in the unknown unknowns category. And that’s no good at all.