Coding Etiquette to Make Other Developers Hate You Less

Ever spend hours searching for an error in the code of a website or app? We’ve all been there. Few things frustrate more than debugging a hot mess of foobar code. It takes longer than it should to find errors, which takes away precious time from getting real work done.

The good news is it’s fairly easy to write clean, manageable code that makes other developers and your future self happy. I’ve saved you years of making the same mistakes I did by compiling them here in one safe place for you.

0. Comment Your Code

What’s worse than uncommented code? If you said anything, you’re wrong. If you’re going to do anything at all to improve your code, make sure you comment. Comment loud and proud. Comment ’til the cows come home, then comment in their faces some more. Then tip them when they fall asleep, so much fun.

Just finished a big, game-changing function? Do yourself and the world a favor; type out what it does and how to use it. You’ll be thanking yourself six months later. Plus it’ll help you avoid death threats written in Binary from co-workers.

1. Now Make the Comments Actually Make Sense

You’re writing comments! Great job. Now it’s important that your comments tell your fellow programmers what is actually happening in a clear and concise way. Remember, we’re all our own special unicorn; we all think differently. Jedis don’t have time for your Klingon (or your cross-universe metaphors).

You should also avoid restating the obvious. Take the example below.

$variable = 0; // Setting the variable to zero

If what you’re doing is basic and clear to a beginner, don’t bother commenting it. We genuinely appreciate the enthusiasm and commitment to the cause, but some things really are self-explanatory.

2. Don’t foobar all over the place

Use solid, descriptive variable names. You’ll find your code basically comments itself. Variables should be named for what they do, or what they represent. Not your favorite Transformers.

$megatron = str_replace($thing, thing2, $redfishblue);

Do you have any idea what that block of code does? I think Megatron is hungry?

The same principle applies to short variable names. Unless you’re using accepted standard abbreviations, use full words. Random letters will confuse just about every programmer that reads your code later.

$gc = m($g, $u, $t, $f);
echo $gc;

We understand it. That’s all that matters, right?

If your variables look like this, you’re on the right track.

$postTitle = get_the_title();
$filteredTitle = str_replace( "&", "&", $postTitle);
$postTitle = $filteredTitle;

3. Nesting isn’t just for birds

Now that you’re commenting and writing whimsical variables, you’re halfway there. Congrats! Now it’s time to make your code readable. Nest your code blocks so that the hierarchy is clear. Properly nested HTML will make using the right CSS selectors a breeze.

Find the bug.

<div class="awesome"><p id="awesome1><a href="http://www.superlong.com/plicated?link=with&plenty=ofquerystrings"target="_blank">Everything is Awesome</a></p></div>

Try again.

<div class="awesome">
    <p id="awesome">
        <a href="http://www.superlong.com/plicated?link=with&plenty=ofquerystrings" target="_blank">Everything is Awesome</a>
    </p>
</div>

You could try to argue that Developer Tools will indent your code in the Inspector anyway, but if your code doesn’t look like it does in the Inspector, how the heck is anyone supposed to find that missing double quote?

4. Follow Your Community Standards

These basics will get you into the party, but if you want to stick around you’ll need to go a step further. Every development community, whether it’s WordPress, Django, or jQuery, has its own set of coding standards. Follow. Them.

The quickest way to ruin your reputation as a programmer in any given community is to ignore the accepted standards. Always check for the standards before you get too set in your ways. Once you have a bad coding habit, it’s exceptionally hard to break.

For more on WordPress standards, check out the WordPress Codex.
For Python standards, check out the PEP 8 Style Guide.
For other languages, check out Google.

5. And Finally… Have Fun

Programming is one of those great professions where we get to wear jeans and t-shirts and beards to work every day. It’s supposed to be fun. You can do unbelievable things with code – things that literally change the world.

But when you’re spending late nights slogging through 2,000 lines of lumped together CSS, trying to fix that one IE7 bug you have left, you (or someone you wouldn’t wish this on) won’t be having a lot of fun.

If you follow these basics, you might not get teamed up on by five hostile developers at your company’s next Catan competition.