/_ Always code as though you're teaching someone. _/Posted on: November 12, 2012

... or...

// Force yourself to code better through imagining that you're teaching others.

One of the greatest things about this big old world wide web we all love to spend so much time with is that it has a great community culture about it (well, for the most part). It's also becoming easier and easier to learn how to become a web developer with sites (or movements) like TreeHouse, the recently launched Web Platform Docs, and Code Club. There's also the chance to regularly meet up with other local developers by attending Meetups, and even the chance to get your hands on some of the biggest projects in the web industry over on the much beloved Github.

As with most things though, there's always room for improvement, and this is what I hope this post encourages (as well as pleasing my mild case of OCD).

On a few occasions now, I've wanted to help contribute to some relatively large open source projects, but going through the code was like trying to solve a mystery (and not even from lack of a basic understanding of the language in use on my part). This is simply just not how the "open" web should work. Hopefully what follows is enough to convince you of how it could be better.

Why should you want to?

The web is about openness. Enough said.

On a more practical level: it's easier for you to remember what you've done, and in teams or open source projects, it's not a nightmare for someone else to jump right in. At the end of the day, you're either making sure that others are happy to contribute to your project, or you're saving your company the time other developers would have to spend deciphering your code.

Remember, not everyone thinks like you do so the way you've done something - while perfectly sensible to you - might confuse the heck out of someone. Even (and sometimes especially) if they're more experienced than you.

Lastly, you'll quite often discover things that you would've done wrong had you not planned it out with a descriptive comment beforehand.

How do you go about doing this?

You should provide or use minified code for front end code anyway (see below for more on minifying), so be verbose with your comments! Rather have too much and make sure that people know what's going on. Now: this is obviously within reason. Nobody wants to scroll through a short story to get to your code. Be as terse as possible, while still getting as much across as you can. Also try to break your comment up into smaller bits if necessary, so rather than an extensive description detailing everything that a particular function does, make the comment be a quick overview and then provide further comments within that function on what each bit is doing.

Be descriptive with your variable names (but not overly so). If necessary, leave a comment about what exactly a variable is for. What's most important here is that it makes sense where it's actually used.

// This is not a very helpful variable name.
var name = true;

if (name) {
  /* code here */
}

// This would be a much better way to name it.
var hasName = true;

// It makes sense where it's used.
if (hasName) {
  /* code here */
}

Use a decent code minifier for your client side code so that being verbose with comments and descriptive with your variable names doesn't have an impact on your site's performance. Most minifiers will strip out comments and put everything on one line. Good minifiers will intelligently change all variable names to be as few characters long as possible (also known as obfuscation). If you don't use a build tool such as Grunt, then I generally used to find JS Compress to be pretty good.

As for server side code, most (if not all) of the parsers for these languages shouldn't be affected by comments. In situations where the opposite is true, it would be a case of the server that's doing the processing which would be more likely to cause issues (if any). In such a case, some caching is worth looking into but that's not a language agnostic topic so I won't get into it here.

This goes for any programming language, whether Javascript, CSS, PHP, Ruby, MySQL, etc... the only exception I would say is HTML comments. Unless you can find a way to remove them in production code, they make your page heavier to download and are visible when viewing the source code.

Last, but definitely not least: put some personality into your comments. Let loose... have a little fun now and then. Reading through mountains of code can - believe it or not - sometimes be boring and a snarky comment/joke here or there can help lighten the mood a bit!

Some example ones I scoured off the web:

doRun.run(); // ... "a doo run run".

yArr[3]; // Pirate pun intended.

stop(); // Hammertime!

To conclude

Put yourself in other's shoes. Try to imagine what someone new to your code/the project - who is potentially of less experience - might be thinking while reading it. When you're done with a particular piece, re-read the whole thing to make sure it makes sense.

Just remember that there's always, ALWAYS someone that can learn from you! Here's to making the web a better (and more fun) place to be!