As a professional web developer — employed or freelance — you will be working on code that other people have written around 90% of the time. And after you’ve done your bit, it’s likely that someone else will be working with your code.

I recently worked with a junior developer and I had a lot of trouble understanding his code. Here are some of the mistakes he made, and that I also made when I was a beginner:

Thinking about style and structure at the same time

We all know that we need to keep style and structure separate, that the different technologies of HTML, CSS and JS should not be mixed. We don’t do inline or embedded styles anymore, we keep our JS separate from our HTML, etc…

But, do you keep them separate in your head while coding? Or are you already thinking about the styling you want to achieve while writing out the HTML structure?

Although it might make the styling easier, this is usually a bad practice for beginners.

You can tell when someone has written HTML with the styling in mind. It’s not structured logically, it’s not accessible, it often isn’t semantic, and not SEO-friendly.

If you’re a beginner I would recommend forgetting about the styling while you write your HTML.

The HTML page should be able to stand on its own. Think about this:

  • If you switch off all CSS, will the page still make sense? Is it readable from top to bottom?
  • If a blind person is using a screen reader, and it reads top-down, is it possible to use?
  • If Google is crawling the page, is content grouped together in a way that makes sense?
  • If another developer reads the HTML code, will they immediately be able to understand the page structure?

So write solid HTML first, make a logical structure, keep it simple. Then start the CSS.

Of course, more experienced developers will often write everything at the same time, but that’s because they no longer need to think about the points above, it’s a habit.

Learn the rules like a pro, so you can break them like an artist.
— Pablo Picasso

Not caring about class naming (or not naming things at all)

In programming, naming is everything. You must have heard people say this before. And although CSS is fairly ‘easy’ compared to actual programming, naming is still super important!

In fact, naming is so powerful that it can solve your problems for you. For example, sometimes I’m struggling with the layout of a certain section and I just can’t build it in a way that makes sense. I then take a step backwards and reconsider what I’ve named it.

Does the name accurately describe it’s function? Is it an option-switcher or is it really just a toggle? Oh, at its core it’s really just a toggle! Suddenly everything falls into place and it becomes much easier to build. Why? Because I’ve rebuilt my mental model — my understanding of the problem.

If I had an hour to solve a problem I’d spend 55 minutes thinking about the problem and five minutes thinking about solutions.
— Albert Einstein

Simply naming an element correctly can give you the solutions to your problems.

The other reason naming is important is that it helps you communicate with the next developer.

If I’m reading your CSS and see this:

div + div { 

}

That tells me absolutely nothing about what class is being styled. I’m forced to open up the HTML and check where there is a div and then another div.

If the class was more descriptive, then sometimes I could immediately make some change to it without even checking the HTML, because if it’s named well then I know with 95% certainty that I am indeed styling the right thing.

The CSS should be readable on its own, without having to check back to the HTML too often.

Not indenting and spacing your code properly

When you write code, you are not only writing for the computer. You should also keep in mind that you are writing for other developers too. This is often just an afterthought for many developers. “Oh yeah, I should add a comment maybe”.

But what if we put as much effort into the readability of our code as we did with our blog posts or emails?

When you write a blog post you use spacing, bold and italics, dot points and other formatting to make things more legible for your reader. Well, in code you use indentation, spacing, and comments.

Indentation in HTML allows you to easily see the parent and child elements, to minimize and maximize code blocks, and if using a templating language — to see loops and if statements easily.

In CSS, and especially in SASS or LESS, indentation shows us the scope of what we are styling, and saves us from having to figure out which bracket closes a code block.

Vertical spacing is often ignored but also very important. It should be used to separate ideas. I usually use two lines of space between any major code blocks or anything that I want to be visually obvious or stand out.

And as for comments, the more the better. I’ve never seen someone complain about too many comments!

Not using a coding style guide

A style guide describes how your code should look. I believe the term is taken from designers that have a style guide to stay on-brand. If you’ve never seen a style guide then I recommend checking out the CSSWizadry or Google style guides.

The point is that all of a companies code should look as though it’s written by the same developer. This applies to freelancers too, when you’re working on a project that someone else built it’s best to continue in the same style as the previous developer.

A coding style guide is especially important when you are a junior because it teaches you good coding and thinking habits. You will find things much easier if you just stick to a style guide and doing things the ‘correct’ way rather than coming up with your own structures or solutions.

If you work in a company then a senior developer should provide you with some kind of company style guide. If you work alone then I recommend using one of the guides I linked above.

Trying to fix a bug without finding the reason for the bug

If you just put a patch on a bug without knowing why it happened, it will come back to bite you later. This is a fact of life.

I know, you may be approaching a deadline and you don’t have time, you just stick some duct tape on the bug and forget about it. It happens.

But, if there’s no looming deadline then you should definitely dig into the reasons behind the it. Not only will you do a better quality job, but you will grow in your understanding of code, and won’t make the same mistake next time.

If you just patch up a bug without truly understanding the reason, you will have to do that the next time it happens. It will become a crutch for you and you will be a worse developer because of it.

Not going with the flow

AKA the tao of web design.

There is a certain way things on the web are designed to work. The most simple example is a raw and unstyled HTML page, it just works.

There are also certain powerful features that let you break that natural order. For example, using absolute positioning — although a valid technique — should not be over-used. Another example is using exact pixel-heights. Or using javascript to achieve a certain layout. And please limit your use of !important to like, once a year.

If you break the natural order too much, you will end up re-inventing the wheel. And unless you’re a genius, your wheel will be worse than the one that already exists.

So try to look for the proper way to do things. There is a time and place for using clever hacks, and that is when you’re more experienced and only when the situation really calls for it.

All of this really comes down to being methodical in your actions, and also caring about the people reading your code later on. Try to imagine yourself in their shoes — would they understand what you’ve written? Can you explain why you did it that way?

If you’re a junior developer and you need some advice, feel free to reach out on Twitter. All the best!