Minor imperfections that shout ‘beginner code’

For about a year, I've been mentoring a few people who are just getting into programming. While reviewing their code, I have noticed a few issues that appear repetitively. Many of those issues are:

• minor enough to look OK for beginners
• annoying enough to be immediately noticed by more experienced developers

Let’s go through these imperfections quickly so you can avoid them in your code!

No new line at the end of the file

There is a UNIX convention of adding new line characters at the end of each file. It started because command line tools like cat were displaying many files without putting any separators between them. Git identifies files by the hash of their content—even one character difference makes a file different for Git. Those two things combined cause Git and GitHub to point it out whenever there is a file missing a new line at the end of the file.

Git command line:

GitHub:

Many projects I’ve seen have a policy of requiring each text file to contain a new line character—following the UNIX convention.

Solution

There should be an option in your code editor to add those new line characters for you. Alternatively, you can check the support for EditorConfig in your editor and set it up on the project level.

Inconsistent code styling

Please take a look at this code:

if (a == 1){
  b = 2;
} 
else {
  b =3;
}

I used to write like this when I was starting to program, but now I feel almost offended by the code style here. And I’m not alone: other programmers point to consistency as an important part of coding as well.

Solution

You don’t have to:

• perceive all the styling issues, nor
• fix them manually, nor even
• think about code style details.

Rather, just get some popular and opinionated code style automation tool and outsource all your styling needs with that tool. For the frontend, you have Prettier, which I covered in another article.

Commit messages

I’m often sending the commit message guidelines to anybody I start working with. Plenty of projects enforce those rules—or something even more elaborate. Why do I and other people care so much?

• Some projects generate change logs automatically from commits. For example, angular uses conventional-changelog.
• Git history should provide a quick overview about what happened in the project—messy messages make it more difficult to digest.
• git blame points to the commit that changed a given line the last time—a good commit message speeds up understanding what and why happened then.

For a beginner working on a personal project, I would stick to:

• using the verb in first person imperative in the present tense: add index.html instead of added index.html or adding index.html.
• keeping capitalization consistent—either always starting with a lower- or uppercase letter.
• not using a period at the end of the message.
• staying below 50 characters in the commit message. A bit more is fine, but try to avoid going over 70. Most Git tooling doesn’t wrap messages, so long messages will be truncated or go outside of the screen.

!important CSS

When you use !important in your styles, you force a given CSS rule over any other. It’s a code smell, or a way of achieving your goal when things have already started going bad in the project. When you use !important, you are removing a simple option to override the values with more specific selectors—a key feature of CSS. The only situation when you cannot avoid !important is when you override another rule that already uses it, and which comes from code you cannot control—for example, from third-party libraries.

What should you use instead? Any way of making the selector more specific and therefore stronger. In the worst case, you can duplicate class name to make one of selectors stronger:

.side-bar.side-bar {
  color: green;
}

.content {
  color: blue;
}

will make <div class=”content side-bar”>test</div> green.

Folder structure and file names

My expectations about codebase structure are that:

• it should be clear what I will find inside any folder or file,
• it should be obvious where the new code that I’m about to write should go,
• it should be consistent, and
• it should be rather simple.

Examples that don’t meet those expectations:
*

controllers/
  some-controller.ts
  anotherController.ts

The above mixes kebab-case with camelCase in file names: it’s unclear how the new files should be named.
*

admin/
  some-class.ts
classes/
  another-class.ts
views/
  index.html

The snippet above mixes folders matching use cases (admin/) and folders matching file type (classes/). It’s unclear where the admin-related class belongs.
*

very/
  nested/
    folder/
       file.ts

And finally, the above is more nested than necessary.

Summary

Those few things look rather minor for anybody who’s just starting to program, but it’s common for experienced programmers to pay attention to and notice them. Getting that straight sooner than later is a good idea: it will make your code look more professional, and doing so will help reviewers to focus on more important things.