What’s that smell?
We will all have to work with someone else’s code at some point. Not all code written by others is bad, even though our natural inclination is to think so. How can you tell that the code you’re dealing with is a problem? Here are a few signs:
- Missing or incomplete documentation: there’s some part of the code for which there isn’t a good reference to understand why it exists and what it does.
- Missing or incomplete tests: you can’t be sure that a change you’ve made hasn’t broken expected behavior.
- Fear of change: you genuinely feel fear when touching the code because you’re not sure what the end result will be.
- Fragile code: changing one seemingly isolated piece of code has ripple effects throughout the software that are hard to predict.
Code Conventions
When I was studying computer science in college, I had one extremely tough professor. His name was Dr. Maxey and he taught the more complicated courses like data structures and computer architecture. He was a wonderful teacher with a talent for articulating difficult concepts, but also an extremely tough grader. Not only would he look over your code to make sure that it worked, he would subtract points for stylistic issues. If your code lacked appropriate comments, or even if comments contained a misspelled word or two, he would deduct points.
What’s a Style Anyway?
Coding style is how your code looks, plain and simple. And by “your” I actually mean the code written by you, the person reading this chapter. Coding style is extremely personal and everyone has their own preferred approach. You can discover your own personal style by looking back over code that you’ve written when you didn’t have a style guide to adhere to. Everyone has their own style because of the way they learned to code.
It’s Personal
- The personal nature of coding style is a challenge in a team atmosphere. Often, seeking to avoid lengthy arguments, teams defer creating style guides under the guise of not wanting to discourage innovation and expression. Some see team-defined style guides as a way of forcing all developers to be the same.
Leave Yourself Clues with Comment
If you know your enemies and know yourself,
You will not be imperiled in a hundred battles.
—Sun Tzu, The Art of War
Make Errors Obvious
One of the most important reasons to have a coherent style guide is to help make errors more obvious. Style guides do this by familiarizing developers with certain patterns. Once you’re acclimated, unfamiliar patterns jump out of the code when you look at it. Such patterns aren’t always errors, but they definitely require a closer look to make sure that nothing is amiss.
Architecture
There is an interesting tension between developers and architects in most software engineering organizations. Developers see architects as theoreticians who like to draw diagrams and make proclamations about how software should be built, without taking into account that the world isn’t perfect.
Truth be told, there are architects who fit that description, but good architects are priceless commodities who increase the value of an entire organization through their high-level vision and perspective. Such vision and perspective transform architecture. For writing a java script assignment, you need a web browser and either a text editor or an HTML editor. Once you have the software in place, you can begin writing JavaScript code.
Last Word
There’s a reason why popular open-source software asks for and spends time on contributions to its documentation: if software is hard to use or too opaque, then people won’t bother with it. Yet the same developers who regularly complain about some software’s lack of documentation are the same people who look for excuses to not write documentation for their own software. Good software is well-documented software, and bad software has little documentation. There is no such thing as maintainable code that isn’t also documented.
