"Even bad code can function. But if the code isn't clean, it can bring a development organization to its knees." — Robert C. Martin (Uncle Bob)
- Variable and Function Naming Conventions
- When/If To Use Global Variables
- Keep Functions to Performing One Job at a Time
- Utilize Progressive Enhancement
- Use JSLint to Ensure Syntactical Quality
- Placing Scripts at the Bottom of the Page
- Commenting Best Practices
- Software Alternatives to Commenting
Variable and Function Naming Conventions: Clear, Concise & Comprehensible
One of the first, and arguably most important best practices are to name variable and functions properly. Almost any developer can relate to jumping on a project and feeling the frustration ensue after coming across variable with short, undescriptive names like FQ1 or X9 or long, arguably too-descriptive names like UpdateNotificationHandlerIfFullMoon.RegisterMiddleWare. Don't get us wrong; there are a time and a place for short names and more descriptive names; just try not to go overboard on either.
Generally, you want to keep names as concise as possible without skimping on too many details. However, it can be hard to keep names brief when the category name and parents both have long names. But ultimately, the more concise, the clearer, and inevitably, the more comprehensible.
"There are only two hard things in computer science: cache invalidation and naming things" – Phil Karlton
Global variables best practices can seem a bit convoluted online. Some recommend omitting them altogether, while others recommend reducing your use of them when possible.
If a variable is declared outside a function, it's global. When this occurs, all functions and scripts on a webpage can access it. So, why the hate from many developers? Some argue this can be dangerous as scripts included after yours that contain the same variable or function names can overwrite your variables/functions.
"By reducing your global footprint to a single name, you significantly reduce the chance of bad interactions with other applications, widgets, or libraries." Douglas Crockford
Compare it to this version below. The function is the same; however, by reducing the footprint of the 'DudeNameSpace" object, you've reduced the possibility of having other variables or functions overwrite it.
Functions: One Job At a Time
If another developer joins you on your project, tries to build on it, or attempts to debug it or change it, they won't have to read through the entire code document to figure out what code performs which functions.
Keep in mind that this is incredibly relevant when creating common tasks or helper functions. Let's say while working on a project you realize you've been doing the same thing in a few different functions over and over again. To save time, you can create a more generic helper function, then reuse that functionality where it's needed.
Restricting your functions to only completing one job at a time also means you can change to an application or remove functionalities easier, quicker, and more accurately.
Utilize Progressive Enhancement
Use JSLint to Ensure Syntactical Quality
Clean and valid code should be the goal of any developer. It means more clarity, fewer bugs to fix, more straightforward handover to other developers, better security, and, ultimately, fewer headaches.
The best part? There is a nifty tool that makes it easier than ever: enter JSLint.
It provides a detailed report on any syntax warnings and what they mean. However, consider yourself warned. If there are any errors, JSLint WILL find them, and won't spare your feelings in doing so.
"JSLint will hurt your feelings. Side effects may include headache, irritability, dizziness, snarkiness, stomach pain, defensiveness, dry mouth, cleaner code, and a reduced error rate." – Douglas Crockford
Place Scripts at the Bottom of the Page
One way you can quickly achieve this is by placing scripts at the bottom of the page.
When a browser is loading a script, it won't continue until the entire script has loaded. For example, if you've placed a script near the top, users will have to wait longer before noticing any progress. Do yourself, and future users a favor and make sure any JS files, especially those with the sole purpose of adding functionality, are placed at the bottom right before the closing body tag.
A Comment about Comments: Only When Needed
When done right, comments never hurt anyone. By right, we mean ensuring your comments don't end up in the code that users see. If they do, you're not commenting right. As long as you steer clear of that, and use moderation, commenting can be an incredibly useful tool.
Software Alternatives to Commenting
Like we mentioned, when used right and in moderation, commenting has the potential to be a powerful tool. However, it's easy to overuse and could cause problems down the road.
Instead of commenting, one of the best internal communication tools you and your team can use is CloudApp.
CloudApp can enable you to communicate visually with your team in mere seconds (let's be honest; coding involves enough typing as it is). Whether you need to annotate a screenshot, create a quick GIF, or make a quick screen recording to show precisely where that bug is, CloudApp can help.
Don't forget to pick up a free trial of CloudApp to try out with your team!