General Coding Guidelines

Before jumping into language-specific styles, it would be good to touch upon several guidelines to ensure you’re on the right track, despite what language you use.

Comments

One of these very important components is how you leave comments on your work. You will sometimes find code that baffles you, and it just so happens that half the time, the confusion comes from the code having very little explanation. It takes practice to master and the foresight to write good comments for the sake of future developers, and it sure helps to know where to begin.

Here’s an example of a bad comment versus a good comment:

Bad:

// For loop
for (let i = 0; i < length; i++) {
    console.log(i)
}

This comment merely states what the following lines of code concern. This is of no help to the programmer. Unless the situation calls for it, it’s often that you’d be more helpful talking on what a block of code is doing or why it’s needed, rather than what it is at its core.

Good:

// Print numbers from 0 to length, to the console
for (let i = 0; i < length; i++) {
    console.log(i)
}

As you can see here, this easily tells the reader what the for loop is trying to do, without getting too verbose. Now some may argue that you might not have to be so descriptive for a snippet of code so self-explanatory, so it really depends on how complicated the code is, if you want to leave certain comments or not. You do not need to comment on everything you code.

Quick Notes:

• Good rule of thumb: If you, the writer, have trouble understanding some components you typed up, then it certainly could use some comments to help future developers that read over your code.
• A lot of debugging requires you to trial and error code and comment out a debugging console.log or two. Make sure to delete these when you find and fix issues, as this may confuse future developers if they’re left stranded in your code.

Clear code > brief code

As you’re coding and learning creative ways to rewrite the same code, it may be tempting to condense it all into one line, or push it all together to save space. While sometimes it’s useful to condense code, it may actually harm the readability of the code you write. One good example is:

if (var2) var4 = (var3 ? true : false)

Not completely unreadable but it makes your brain itch a little bit, right? Doesn’t exactly tell you what it’s doing (coincidentally this is where comments could be useful as well). There’s a better way to write this:

if (var2) {
    noDashErrors = (var3 ? true : false)
}

A little better, right? Now it’s a little clearer to see that this assigns var4 the value of true if var2 equals 0 and var3 is true. Let’s be honest though, this still looks very janky. That’s where good variable names come in.

As much as you’d be tempted to condense code, you’re also likely to want to write as little code as possible, specially for variable names. This can be seen above with the non-descriptive variable names we used. A great variable is self-explanatory. Let’s rename the variable names to something a little more descriptive.

if (systemsReady) {
    noDashErrors = (initialChecksPass ? true : false)
}

Here we see the code makes a little more sense! Assuming this is code for starting a vehicle, checking that the system is ready to go and that initial checks are successful, there will be no errors popping up in the dashboard. The code could use some comments for further clarification but it’s clear to see this is an improvement from the variable names alone.

• Note: Whether you use camel case, or snake case (systemsReady vs systems_ready) would largely depend on the syntax of the code you’re working on. Strive to keep the style of your files consistent.

Indentation

This can be incredibly important for code readability, sometimes even as much as variable names and clear code. Depending on the codebase you’re working on, you may find yourself indenting using tabs or spaces. Keep it in mind and stay on top of it so you don’t find yourself puzzled with code you wrote, when you’re busy debugging.

if (systemsReady) {
    if (initialChecksPass) {
        noDashErrors = true
    }
}

is far more readable than

if (systemsReady) {
if (initialChecksPass) {
noDashErrors = true
}
}

Both work the same but which would you rather look at? Exactly!

That concludes some general tips to keep in mind. Keep reading to get familiar with styles specific to programming languages!