Why does my code look like spaggetti?

From Image from degrassi.wikia.com

I recently received an email from a fan asking a question:

Hi Omar,

I'm learning to code. However, it gets really difficult after the 100th line. When I pick it up again, I have to spend about an hour trying to understand everything. What can I do?

Cheers,

u/T-REX-SLAYER-542 (Reddit user)

Well, you're in luck T-REX-SLAYER-542. I'm going to put my chef hat on and try to untangle the mess you made.

Actually, I won't. No one will want to work with your code. It might be awesome, but you're probably not paying attention to a few principles that allows you to make your code understandable to other developers.

Imagine you're writting a Games of Thrones type novel, you created 70 characters with weird medieval names, and now you put the same storyline and narrative as Cloud Atlas (i.e. future, past, convoluted stories), then you copy-pasta (haha) it into Google Translate and go crazy English-> Macedonian -> Korean -> Latin -> English. You get the picture? I know people that would rather read that novel than taking a stab at understanding your code.

Some people say that you should always code taking into account [some scary psychokiller/monster/politician] is also a developer, has to deal with your code, and knows where you live.

I know, we're all learning. Let's work on adding some clarity into your codebase!

1. Style

The first thing people do when trying to program is to use the same notations they've learned in algebra and use it for software engineering. This is commonplace in universities that try to give students math related toy problems (nth prime numbers, remainders, etc). However, it is very unlikely that you will be doing these kind of algorythms throughout your carrer as a developer.

We will only focus on variable names here, as this is probably going to make the most important style decision you could make.

Here's some fast tips:

  • Your variable names should be explicit and understandable on the first time someone else reads them. Example:
    javascript // bad x = ['Iron Man', 'Captain America', 'Hulk'];

    javascript // good avengers = ['Iron Man', 'Captain America', 'Hulk'];

  • Array's should be writting in plural
    javascript // bad avengerArray = ['Iron Man', 'Captain America', 'Hulk']; javascript // good avengers = ['Iron Man', 'Captain America', 'Hulk'];

    Everyone will know that this is a collection (grouping of similar elements) of avengers.

  • Long expressive variable names are much better than short concisive ones.

    We're not in the `90s anymore. Your floppy disk will not run out of memory if you have really long variable names. IDEs will autocomplete stuff for you if you hit the tab key. This is probably the only instance where developers should not be lazy.

    People that read your code could much easier understand a function name called multiplyEachPropertyby2() than one called multBy2. You know that the first one works with objects, the second one is a big blur unless you read a comment or read its code (which is probably 5 folders deep, in the middle of a utility file).

2. Separate Concerns

This one is really really tricky to understand. It's quite abstract. It's about having a particular module of your code do only things that concern it.

A mailman could drive a mail truck, deliver mail and pick up mail.
A milkman could only drive a milk truck and deliver milk.

If you have a mailman driving a milktruck (because he's friends with the milkman and it has better mileage) it will confuse everyone and will bring chaos to our imaginative universe.

Make everything do what it is supposed to do. Each to its own. Don't stir things up. Keep everything in place. Separate Concerns.

3. Other

There's a lot more other things to think about, you should read Clean Code if you're up to it. It's a really awesome read. Make sure you have at least 5k lines of code done before you dwell into it. This way you will facepalm when you realize the stupid things you've done (we all go through this).

Need more help on this? Go find a style guide! Some really awesome companies have open source how they organize their code. Here's my favorite for javascript.

P.S: I don't really have fans. But I really hope that there's a reddit user named u/T-REX-SLAYER-542

comments powered by Disqus