Not too long ago ID Software published a document detailing its coding guidelines. It makes for interesting reading and we can all learn something from it.
I certainly picked a few rules from it as I was putting together a set of coding guidelines for cloudbase.io.
However, web development is very different from game development. Iterations over a piece of software in the web world can be as brief as half an hour, production bugs need to be fixed and released promptly. When building a game you spend months testing and refining your code.
Fast iteration is one of the biggest advantages of web development, a centralised code-base that can be adjusted and updated without needing to re-distribute your software. Unfortunately the speed of development and release is also what causes “spaghetti” code to appear.
What I thought I’d do is try to set, on top of some detailed coding standard rules, more architectural and structural rules for the code. These will hopefully guide developers when they are furiously fixing issues and adding functionality.
These are in no particular order and I’m writing them as they come to mind. I would like to hear from developers and CTOs out there to complete and adjust this list.
- If parts of your software need to interact with some code without knowing its entire structure and meaning, in an interface-like style, then it should be an Object. Weakly typed languages are no excuse to produce code that will be harder to debug and maintain in the future.
- Your variables should be your comments – use readable variable names and split an instruction in three separate steps if needed for the sake of readability.
- Think big – when fixing a bug or adding new functionality think about the rest of the code and how it interacts with what you are re-writing, you are most likely missing something. Then pause again and think even bigger, what will your business look like in the future, in which direction is it heading, perhaps you could add some hooks in your code which will make it easier to re-use as your software evolves.
- Objects are nice and keep your code clean – however, if the object you are creating will not be reused, or you already know it can’t be reused because it’s not going to be compatible with the rest of your code, then it probably shouldn’t be an object, keep it simple.
- Divide to conquer. If your application can be separated in different components, for example an API and a management console, make sure they can run independently from each other. If one is down ideally it shouldn’t take down the other. This will also make your code easier to re-engineer, you will be able to do it one little logical component at a time without having to go through a monolithic rewrite which almost never works.
- If you are writing a 10 lines IF statement there’s probably something wrong with your logic, review and simplify.
- Prototype your code quickly but make sure to cover the entire business case from beginning to end. Once you have mastered all of the use cases, write the code for your application.
- When adding new functionality also write a test case for it.
- If the functionality you are building already exists in a library your project is using or could use, use that library. DO NOT REINVENT THE WHEEL.
- Write some java-doc style documentation for your functions. It will make other developer’s life easier, your business will be able to produce a documentation for all of its code.
- Write comments to explain the logic of your code if it’s needed. don’t state the obvious.
- We are building web apps. The web server is already multi-threaded, each page loads in its thread, you don’t need to spawn sub-threads in a page.