Recently, I’ve been thinking about few common anti-patterns I tend to see in professional JavaScript projects. Today, I wanted to talk about one of them: no docs.
A lot of more seasoned developers have this obsessed with “self-documenting code.”
And its true that if you write functions that do just one thing and follow logical naming conventions, what a piece of code does can often be pretty apparent.
Looking at the addItemToCart() function below, I can pretty quickly determine that I pass in the ID of the item to add, and it updates the quantity of that item in the cart object.
All style guides are poop if they don’t start by setting a context for when the guidelines are to be used. If you are the only developer on a project then spending a lot of time setting up protected access to hidden variables and documenting every function as though this was a public API is a waste of time.
Trust me, just put it all in one big file and use good names for things. Then you can see all the code, know what it does, and easily fix that weird bug that cropped up two years later because of browser updates.
Now if you’re on an actual TEAM of people, that’s very different. Use dependency injection, use high-level (MVP, MVC, MVVM, etc) patterns to organize things, and especially use the documentation comments to describe WHY things work in a certain way. Use good naming and organization to state WHAT things are. “getID” is a terrible function name, but “customer.getID” is an alright method name. “Gets the ID of a customer” is a waste of everyone’s time as documentation, but “Calculates the ID using a hash of customerRecordID and customerSessionID” is a really important comment that will help someone solve a very irritating bug someday.
All these tools like doc comments, readonly access to protected internal state, and all the SOLID principles exist to ease Programming-in-the-Large. That is they help teams of people working on big projects that span hundreds of files. Breaking out all this stuff for solodev applications that have less than 10K lines of actual code is complexity for it’s own sake and ends up making simple applications far less readable and maintainable.