10 Things All Software Engineers Should Know

I am in the interesting position at the moment of managing a team of people writing software who have almost no training or experience in software development. I find two things truly remarkable: first, that any modestly sophisticated working system can be made using code written by people that know almost nothing about software, and second, that smart people, who are motivated, can learn how to do things better pretty quickly.

I chastised one of our developers today for cut-and-paste coding, and only realized in his response that he literally has never had anyone give him feedback or guidance — he didn’t realize cutting and pasting code was bad. It occurred to me that, as a mostly self-taught developer, there were some good books that I read that helped me understand (but these were for C and C++). I didn’t immediately come across anything like that for a modern language.

So I thought I would think about the things I think are most important.

My Top 10 List

1. Names Matter

The names of files, variables, functions, methods, classes, css descriptors and everything else you name should be descriptive of what they are. This is important for readability, to be sure, but there’s a far more important reason: if you cannot describe what something is, you cannot understand what it is. It’s hard to write something well if you’re not sure what it is.

2. Follow Conventions Religiously

How do you name files, variables, functions, etc.? camelCase? FirstLetterUpper? underbar_delimited? ALL_UPPERCASE? Some-ofThisANDsomeof_that? Find a convention that the language you’re writing in uses and use it religiously. Typically constants are ALL_UPPERCASE, often Classes start with a capital. But each language has different conventions. Use naming conventions to help you understand what things are.

Indent your code to represent containing structures. And pick one level of indent. Most languages use four spaces, Ruby uses two. While apparently there’s a debate in the community: my position is: no tabs, use spaces. Any decent programming editor lets you define how many spaces are inserted when you press the tab key.

Braces, spaces, parens, line endings, and ending should be consistent. this=that + the+other ; is not the same as this = that + the + other;.

Figure out when you need no lines, one line, or two between sections of code. Always do it that way.

Consistency in a company trumps any individual pattern. If everyone puts curly braces at the end of the function or class and you’re used to putting yours on the first line under, change.

3. Code Should Look Beautiful

I can tell in an instant whether code might be good, because good code looks good. It is aesthetically pleasing in its layout, indenting, size, and (when displayed in a syntax-aware editor) should look balanced and even. Beauty alone is not sufficient, but it’s absence is almost always a sign of lack of attention to detail.

4. Keep It Short and Simple (KISS)

The single most important programming skill is understanding how to understand your code as small blocks of functionality because it requires that you understand what you’re doing at a level of abstraction that helps keep you out of the weeds of complexity. I love Ruby because good Ruby coders are almost obsessive about isolating out the bare essence of what each step of a program does into a method (which is the object-oriented word for a function). Lots of short, self-contained methods let you test each chunk, and can be given a nice, descriptive name.

5. Don’t Repeat Yourself (DRY)

My example of cut-and-paste coding was bad because the same code was used, for the same purpose in two different places. When I went to make a change, I would have had to make it in two places. This example was in PHP, which (like other languages) has a simple mechanism called “include” that reads a file as though the code were there. Go ahead and cut when you find this case, but paste it into a new file and include it in both places.

A far better mechanism for keeping things in one and only one place is to create a function or method that is called as needed. Functions and methods both have the benefit of being flexible — they can take arguments whose value can cause substantially similar code to use the same basic logic.

6. Don’t Hard-Code

Code like if ($customer_type == “Vendor”)… which tests a displayed value is always wrong. Because anything a user sees is likely to change. If you decide you want to call them “Suppliers” then your code breaks, and to fix, you need to make two changes. I have my editor set to identify stuff in quotes by coloring it pink. Pink isn’t pretty.

Ideally, you store variable values in the database or a resource file (e.g. strings used to allow internationalization). But don’t rely on database key values (typically integers assigned by the database) and think you’re off the hook! If you have a table called customer_type_lookup, and “Vendor” has key value 42, your code shouldn’t read if ($customer_type == 42)… because, … well, for innumerable reasons.

But sometimes, you have enumerations that are just in code — declare constants (or enums, if your language supports them!) that neatly contain sets of values. It’s easier to read if ($customer_type == VENDOR), and that’s the goal. There are lots of ways to avoid hard coding.

Pink is bad.

7. You’re Not A Developer if You Don’t Know Databases

Almost all of the software I have written deals with data, and while there are some alternatives today to handle special cases, most data is stored in a relational database, and is accessed using Structured Query Language, or SQL. The core ability of a relational database is to store data in such a way as to not repeat itself (are you seeing a pattern here?)

To get the data out of a relational database you need to know SQL. Of the numerous people I have interviewed for very well-paying software engineering positions, many have claimed to know SQL. If I ask “a table contains an id, and a person’s first and last name, birthdate, and gender, can you write a SQL statement to get me the data for a person whose id is 123?” they can usually come up with SELECT * FROM people WHERE id = 123;.

But this is not knowing SQL, or databases. If I complicate by saying, “the person has a work, cell, and home phone number, how would you handle that?” people begin to falter. If they put three new columns in the table, I suggest a phone_numbers table, then ask them to get me a person and all of their phone information, a surprising number are stumped. Asking for a data model weeds out even more.

Data is the stock and trade of software development. You need to know how to create, manage, and retrieve it.

8. Same With Regular Expressions

I have also come to see that the craft of programming is blessed/cursed with “regular expressions” (or regex). Who could love something as ugly as /((ht|f)tp(s?)\:\/\/|~/|/)?([-\w\.]+)+(:\d+)?(:\w+)?(@\d+)?(@\w+)?([-\w\.]+)(/([\w/_\.]*(\?\S+)?)?)?/

This is my feeble attempt at writing a regex that matches a URL, like http://www.example.com:80/foo/bar.html or https://example.com and maybe even a bunch more. It’s probably wrong, but even if it were correct, it would be greek to most people. What regex lacks in expressiveness it makes up for in being an absolutely invaluable string parsing tool. I don’t think anyone much cares for regex, but there just isn’t anything better.

The thing is, once you mostly know this stuff, you can quickly write code that will accurately match and extract patterns from strings, efficiently, and in a fraction of the time needed to use string manipulation routines. It’s a necessary evil.

9. Teach Yourself Programming in 10 Years

My wife (also in the software biz) and I have a running joke. A long time ago, there were daytime TV ads running with voiceover by Sally Struthers (of “All in the Family” fame) offering courses for people, presumably out of work, to learn a new trade. The screen rolled along, listing each of the possible course offered halfway through Sally got to “… Plumbing, Bookkeeping, Computer Programming, Refrigerator Repair…” at which point we looked at each other and understood why it was that there’s so much horrible software out there.

Software engineering isn’t as much of a science as it is a craft, like painting, or wine making. Doing it well requires creativity, memory, instinct, the ability to think abstractly, exceptional personal communications skills, patience, tenacity, flexibility, attention to detail, ability to learn continuously, a love of magic, and a lot of other things that, frankly, most people don’t have.

As I was thinking about this post this afternoon, I came across this rather wonderful web page, which laughs out loud at the notion that it’s possible to teach yourself a programming language in 21 days. I highly recommend this short digression: Teach Yourself Programming In 10 Years — being an exceptional developer takes time. Be patient.

10. Make It Work, Make It Beautiful, Make It Fast

One of the Programming Pearls, a book I read when I was seeking the zen of excellent programming is: “code first, optimize later”. It seems that programmers, even very good ones, fall into the trap of thinking something will be slow, and avoid a simple design in favor of the “faster” one. But this is a trap — coding around false obstacles just creates complexity, but more important, takes far, far longer. Getting something to work, in it’s simplest form, as quickly as possible has the enormous benefit of making all subsequent work incremental, as well as the benefit that sometimes things that seem like they are not going to work well work just fine (or more often than not, turn out not to be the actual problem!).

I recently interviewed a candidate for a position (one which I hope he’ll take when he’s ready to leave his current job). He mentioned an aphorism which is a version of mine that I prefer: “Make it work, make it beautiful, make it fast”. This small expansion of “make it beautiful” adds an unexpected twist, and ties some of the ideas I had discussed together. I cannot overstate the benefit and value of aesthetics: code that looks bad, or is hard to read, or oddly indented, or over-commented, or under-commented, or having irregular shape and color is bad code, it’s that simple.

Implementing software is an inherently incremental process. It’s not necessarily linear, either. I am constantly frustrated by the statement “it’s done, just a couple more things”, which I hear as: “it doesn’t work yet”. If it doesn’t work yet, then the more interesting and often more important task of making it beautiful cannot have started in earnest.

Making code beautiful isn’t about getting indenting right and other hygiene, it’s about understanding the structure and purpose of what you have well enough to restructure it in a ways that is consistent, organized, modular, well-named, and yes, properly formatted. If you have three levels of nesting in 30 lines of code (e.g. a big outside loop, some setup, an inner loop, and perhaps a switch statement at the core), it’s probably possible to pull it apart into two or three methods, one calling the next.

The reason it makes sense to make code beautiful before making it fast is that in making it beautiful, you come to understand your code and learn what the right names are, and what the right method signatures are, and what that smallest reasonable chunks of code are. Once beautiful, it’s very easy to test code, and even easier to isolate performance issues. And when you do find a bug, or a slow part, you usually need to make a very small change to make it fast.

And many more…

As I write, I realize I could keep writing, and write more. But if there’s one last bit worth mentioning is that the fastest, most reliable, least buggy, fastest delivered, and most elegant code I ever deliver is the code I do not write. Part of this is understanding the real intent of the problem so that you can understand why you’re doing what you’re doing. Only then, can you ask a question that might allow you to deliver what is really needed, which is often not what people think, and is frequently simply nothing. And part of this is finding something that has already been done and not reinventing that wheel.

Many books about programming have been written. I won’t reinvent!