When you’re not in a production team shipping software, you’re mostly doing pure R&D or building internal tools or building prototypes. These teams usually don’t have a strict code review process or any specific coding guidelines to adhere to. While this lack of process may sometimes be essential for the team to quickly churn out new ideas and experiment a whole lot, it can also become a major pain point. Before you know it, you are at a point of Zero consistency in coding guidelines across the team.
All code should be beautiful – not just Production Software. And if not for yourself, do it as a courtesy to others. For someone who may have to debug your code when you are away on vacation in Hawaii.
I decided to put down a few high level things that one should be cognizant of even when writing non-production software. Remember – this is the least you can do as a responsible s/w engineer!
README is a MUST
Always include a README file with your code that answers the following obvious questions:
- What is this code for?
- How to compile it?
- Any pre-requisites to be built?
- What environment variables need to be set: PATH, LIBRARY PATH etc.
- How to run the executable?
- What is the directory structure needed when executing?
- What output to expect?
- Any OS specific APIs used – if not under #ifdef
Absolutely No Absolute Paths
There should be no absolute paths used anywhere. For e.g. something that looks like C:\users\abc\Desktop\temp\ is a NO NO. One should always define an environment variable and force the user to define it. This is good information to include in the README file.
Inside the Source
- Indentation is very important – aesthetically and otherwise.
- Please add ‘Useful’ Comments – The more the better.
- Remove commented out code which is not needed anymore.
- Meaningful variable names please, avoid int aa or float bb.
- Remove unused functions (or specify why you kept them around)
- No hardcoding please: use macros or request values as user input
- Check for error returns
- Fail gracefully if possible
What should be checked in?
- Source files & Header files in a separate source folder (and maybe an include folder)
- A makefile or, a solution & project file (if using visual studio on windows)
- Input Data files
- Sample Outputs for the input data that has been provided
- A script to run the executable, if not mention the command line in the README
Remember, this is just the bare minimum to keep in mind when building good software that people will want to look at and use. Some times we put so much thought into implementing a complex problem in software that we forget to take a step back and see whether it was packaged in a usable way and whether it is easy to read and maintain. Keep things simple, document as much as possible and have some empathy towards your fellow coders!