Documenting JavaScript

Abstract

In the previous chapter, we looked at object-oriented JavaScript and coding conventions. The purpose of writing OO code and establishing conventions is to ensure that the code is legible and understandable for a developer. A JavaScript engine in a browser isn’t concerned about how neatly your code is written, or whether it makes sense to you—it merely follows a set of rules on whatever it’s been given. It’s more important for you and your team to understand the code you’ve written and how to work with it as this simplifies the task of maintaining your code base. Code maintainability means that teams of any size can collaborate on the same set of files with a common understanding of how to add, amend, and remove parts of that code with consistent results. In addition to the code itself being understandable, you will find you need to add small comments or larger blocks of documentation to explain to other developers, including yourself if you don’t remember your reasoning in future, what task a particular section of code performs and how it is to be used.