Your Programming Style Guide Checklist
Elmer Thomas
Every programming language or framework has a defined coding style guide. It’s generally a good idea to conform to that style guide for the sake of collaboration and maintainability.
In this post, we will walk through the process of creating a personal programming (project level) style guide and templates that will combine to serve as a checklist for your projects. Over time, you will have created several checklists for various development scenarios. The upfront investment to create these documents should save you many hours of time throughout your hacking adventures.
Location
I suggest you create a directory to store these checklists. You will want two sub-folders, one will contain the templates and the other will contain working checklists for particular projects. These files should be versioned.
For the working checklists, as you go through each section described throughout this post, you will fill in the details according to your specific project. In the case of collaborating on existing projects, you will link to the relevant documentation and then add any addendums in your own checklist.
I suggest you create a symlink to your working checklist at the root level of your project called .checklist or something similar.
License
In your root directory, create a LICENSE file with the contents of your chosen open source license. Or if you want to be all stealthy, include your own proprietary license here. Upset Stallman at your own risk.
Readme
Also in your root directory, create your README file. I recommend you do this in Markdown, especially if you are hosting your project on GitHub.
I like to think of the README as a quick start dashboard for your project. It gives an informative overview with pointers to deeper documentation.
Take a moment to think through the following two scenarios when determining the contents of the README:
- The User – Can someone get started with my software as quick as possible?
- Contributors – Can someone easily contribute to this project?
Here is an example of a good README file that could be the beginning of your own README template.
Dependencies and Assumptions
Document any external dependencies with a brief explaination of why the dependency is needed and what version number is assumed. A good place for this to be documented is in the README file.
Another good item for your README is a description of your programming environment. (e.g. language version, OS, testing server description, etc.)
Project Management
Decide on your project management methodology and what tools you will use. For example, you may choose Agile Software Development with Trello or PivotDesk. In other scenarios, a text file or spreadsheet would suffice.
Files and Directories
Decide how you will organize your files and what naming convention you will use. Check out the directory structure for a Ruby on Rails app for inspiration.
If you are rolling your own framework, create a template version of your directory structure.
Documentation
Internal
Even if you are a solo developer, document your code with the idea that someone else will come after you and need to modify your code as quickly as possible. You will thank yourself later.
External
Read what our Lead Developer Evangelist, Brandon West has to say about documentation.
If you are writing an API, check out this blog post I wrote.
Versioning
Choose your versioning solution and make your initial commit. Make sure to exclude any files that should not be versioned, especially any credentials.
Change Log
After every point or version release (which should be tagged in your versioning tool) you should keep a change log. Much of that can be automated, but if the changes were significant, take the time to explain them, maybe even (puts marketing hat on) create a blog post.
Issue Tracking
Some project management tools also allow for issue tracking, if not, consider what tool you will use. In some cases, issue tracking will be all you need for collaboration, see Github for a good example of that case.
Credentials
Decide how you will store your credentials and environment variables, making sure you don’t include private data in your versioning system.
Include a sample version of these files with an explanation of each credential and variable.
Tests
Determine what level of testing you need and create either the initial tests or the scaffolds. At a minimum, open an issue describing what tests are needed.
Consider the following levels of testing:
Logging
Implement a logging system that at a minimum supports error capture. Keep these as verbose as needed. Consider how often you will rotate the logs and how you will access and store them.
Errors and Exceptions
Define the error codes your app provides with clear, useful descriptions. Log all errors both in a log file and on the console. If you are implementing an API, be sure every error you send comes with either a clear description or a key/link that contains the full description.
Database
Define and version your schema. Document the fields and provide sample data. Describe the data store and disclose the version and environment(s) you have tested.
Platform
Describe both your testing and production platform. In both cases, document dependencies and versions.
Configuration and Deployment
Here, automation is the goal. As you go through your initial configuration, testing and deploys, document all of the steps with the automation goal in mind.
Then you could use tools like Jenkins, Travis CI, Chef and/or Puppet to automate the various portions of your workflow.
Consider if your project will end up on a repository or be used as a plugin or add-on. If so, get the official documentation on how to submit your project and make sure your issue tracker reflects these tasks.
Code Style
Each programming language and framework has a style guideline. Either adopt one of these or define your own. Take a look at the Python Style Guide from the official Python web site vs. Google’s version for inspiration.
IDEs and Tools
A good IDE or text editor can go a long way towards saving time. In any case, master whatever tools you decide to use. Set aside 30 minutes a day towards that end.
Look into what automation tools your OS has to offer. For example, in Mac OS X land, there is Apple Script, Automator, Hazel, TextExpander, Sikuli and Keyboard Maestro to name a few. And of course, you could always use your trusty scripting language of choice. Don’t forget about web based tools like IFTTT as well.
Code Review
Just like writers make good use of editors, do the same for your code. Consider using a service such as AirPair if you don’t have someone on your team to help.
Did I miss something? I’m sure I did, so please let me know in the comments and I’ll update the post. We will all greatly appreciate it 🙂
Happy Hacking!
Image credit: TheFW
