Why code is about people and not about computers

It’s easy to think programming is for- and by computers. But at it’s heart programming is just about people. This sounds obvious, but it’s easy to lose sight of the fact that it is actually for- and by people. We’re programming to accomplish goals for people, not computers. At times I need a reminder for this and maybe you do too.

Code makes sense

I personally started coding because I love the logic of it. I definitely have some of the stereotype characteristics; socially-awkard, middle-class white male from the early 90s. Although there was plenty cool stuff to do out there, I always struggled to deal with people. People are not always logical where computers always are. Easy!

When I started I thought code was all about the computer. Making it work as fast as possible, following every single good practice I could find. How wrong was I..

Let’s start by asking ourselves; what is the definition of “code”?

In computing, source code is any collection of code, with or without comments, written using[1] a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source code. The source code is often transformed by an assembler or compiler into binary machine code that can be executed by the computer.

By just reading at the definition there might already be a clue here. We’re using programming- or code in general to -help- us humans talk to the computer and reach our goals. No shit Sherlock!

Code should help people

When your working on an assignment it’s common (I fall for this every single time) to entirely focus on what might lead to best performance for my code or what’s the intended best practice of a language or framework your using. In the core of it, there’s absolutely nothing wrong with that. I mean, your trying to get the best result right?

However have you considered if you colleages will be able to work with this or will they totally stress out by the idea only? Does this also benefit the assignment your programming for?

I have a personal example. For a while now I’ve been trying to get colleages motivated about getting more into the world of JAMstack. Because I think it could add a lot of value for several of our customers.

So I started using it in several projects, but nobody else was really on board just yet. I shared some of the results, people liked it, however they didn’t actually understand the working of it.

In the meanwhile I continued working implmenting this in projects and by then I really started finding a way of integrating it nicely within our current projects and workflows.

By now almost a year later several people have to started working on this. And by now I came to realize that nodoby actually has an understanding of what’s going on in those projects. The code is totally fine, but I never really considered how my colleages would use- and understand it.

Only people need to read and understand the code by looking at it

At first there were loads of questions. I didn’t really document anything and they had hardly any experience with in the matter.

Well them not understanding is their problem right? They haven’t bothered studying whilst you did. Well if your colleages are total dumbasses, sure. However I dare to bet they’re not.

In some cases; yes. Mostly not. There’s loads of thing I could have done different. I could have documented better; kept the code simpler, etc.

In the end it’s way more important that another programmer is able to understand your code as that a computer can. Computers will compile it anyway. As long it’s syntactical correct there won’t be an issue here. I’m not saying you should totally forget about good practices and performance. But it’s important to make sure everybody is still able to understand what’s going.

What if you don’t?

Remember how it feels when you have to debug some else’s project and it’s one big jungle, without any structure that makes sense to you? Documentation? Forget it! Some comments maybe? Nope!

Sucks right? So just do it.

Some guidelines

There’s some really simple things you could do to help others understand you code. Here some examples of things I try to use.

Follow common design principles – Design principles exist for a reason. If you stick with common patterns it will be easier to understand how code is structured.

If you’re using a Framework, stick with it’s philosophy – If your using any type of framework there’s usually a predefined way a project should be structured and some default framework functionality and utilities. Use those, this is the same for everyone and will therefore help others.

Use correct naming for variables, functions, classes, etc. – There’s nothing wrong with a long name if it creates clarity on what is/does/contains

Comment your code if something’s a bit complicated, or for example if you’re doing something out of the ordinary. This helps other (and yourself in the future) understand why something is done the way it’s done Comment a link to a stackoverflow article if that’s used for some code fragment. You’ll thank yourself later if you’re debugging it

Write documentation on what you’re building – It doesn’t have to be a full book. Just a few lines, depending on the size of what your building. Also add changes, and why they happened. This should be something that takes a few minutes at most. Don’t make it too big. This helps others understand what something is about and how it works. Tip: Use the Wiki on Github/Gitlab.

If your sticking with those simple things, it won’t take much time. Wouldn’t you love it if all your colleages would do this?

What else could you do to help others- and not just the computer understand your code?