Table of Contents for
Maintainable JavaScript

Version ebook / Retour

Cover image for bash Cookbook, 2nd Edition Maintainable JavaScript by Nicholas C. Zakas Published by O'Reilly Media, Inc., 2012
  1. Cover
  2. Maintainable JavaScript
  3. Maintainable JavaScript
  4. Introduction
  5. Preface
  6. I. Style Guidelines
  7. 1. Basic Formatting
  8. 2. Comments
  9. 3. Statements and Expressions
  10. 4. Variables, Functions, and Operators
  11. II. Programming Practices
  12. 5. Loose Coupling of UI Layers
  13. 6. Avoid Globals
  14. 7. Event Handling
  15. 8. Avoid Null Comparisons
  16. 9. Separate Configuration Data from Code
  17. 10. Throw Your Own Errors
  18. 11. Don’t Modify Objects You Don’t Own
  19. 12. Browser Detection
  20. III. Automation
  21. 13. File and Directory Structure
  22. 14. Ant
  23. 15. Validation
  24. 16. Concatenation and Baking
  25. 17. Minification and Compression
  26. 18. Documentation
  27. 19. Automated Testing
  28. 20. Putting It Together
  29. A. JavaScript Style Guide
  30. B. JavaScript Tools
  31. Index
  32. About the Author
  33. Colophon
  34. Copyright

Part I. Style Guidelines

“Programs are meant to be read by humans and only incidentally for computers to execute.” —Donald Knuth

When a team is brought together for the first time, everyone brings with them their own ideas about how code should be written. After all, each team member comes from a different background. Some may come from one-man shops where they could do whatever they wanted; others may have been on different teams that had particular ways of doing things that they liked (or hated). Everyone has an opinion about how code should be written, and it usually falls in line with how that individual would personally write it. Establishing style guidelines should always come as early in the process as possible.

Note

The terms “style guidelines” and “code conventions” are often used interchangeably. Style guidelines are a type of code convention aimed at the layout of code within a file. Code conventions can also include programming practices, file and directory layout, and commenting. This book is actually a collection and discussion of code conventions for JavaScript.

Why Style Guidelines?

Figuring out style guidelines is a process that typically takes longer than it should. Everyone has an opinion and, when you’re going to be spending eight hours a day writing code, all programmers want to do so in a way that is comfortable to them. It takes some compromise within the team and a strong leader to move the conversation forward. Once established, style guidelines allow the team to work at a much higher level, because all code looks the same.

Having all code look the same is incredibly important on a team, because it allows:

  • Any developer to work on any file regardless of who wrote it. There’s no need to spend time reformatting or deciphering the logic of the file, because it looks the same as everything else. If you’ve ever opened a file and immediately fixed all the indentation before starting your work, you can understand the time savings consistency provides when working on a large project.

  • Errors become more obvious. If all code looks the same, and you come across some code that doesn’t, you’ve likely found a problem.

It’s no wonder that large companies around the world have published style guidelines either internally or publicly.

Style guidelines are a personal thing and must be developed within a team to be effective. This section of the book lists recommended focus areas for the development of your JavaScript code conventions. In some cases, it’s impossible to tell you that one guideline is better than another, because some are just a matter of preference. Rather than trying to force my preferences upon you, this chapter highlights important aspects that should be covered in your style guidelines. My personal code style guidelines for JavaScript are included in Appendix A.

Useful Tools

Developing coding guidelines is difficult enough—enforcing them is a whole other story. Establishing agreement among your team and performing code reviews will get you part of the way there, but everyone slips up once in a while. Tools help to keep everyone on track. There are two extremely useful tools for style guidelines: JSLint and JSHint.

JSLint was written by Douglas Crockford as a general code-quality tool for JavaScript. It began as a simple utility for finding common problematic JavaScript patterns. Over the years, it has evolved into a tool that not only finds potential errors but also warns about stylistic issues in your code.

Crockford wrote his ideas about JavaScript style in three different pieces:

JSLint now incorporates many of Crockford’s style preferences directly, frequently without the ability to turn them off. So JSLint is a good tool—provided that you agree with Crockford’s style guidelines.

JSHint is a fork of JSLint that is maintained by Anton Kovalyov. The goal of JSHint is to provide a more customizable code quality and style guideline tool for JavaScript. With the exception of syntax errors, it’s possible to turn off nearly all warnings in JSHint, allowing you to fully customize the messages you receive about your code. Kovalyov encourages participation and contribution to JSHint through the source code repository at GitHub.

Integrating one of these tools into your build process is a good way to start enforcing code conventions as well as catching potential errors in your JavaScript code.