Coding styles for Open Source Projects?
This has also been published in ITNEXT
How to maintain coding styles when contributing
Something I forgot to mention in my previous article was the fact that the repository I was doing a pull request for had a guide for contributors. This post outlines how you can enforce coding standards and styles to your projects.
How to maintain coding styles when open sourcing your own projects
Everyone has their own style of writing code. When you open source your project you want to ensure that the style you wrote your initial commit in is enforced for the lifetime of the project.
Previously this was a task that was reserved for the code review process. You would review someones code and casually mention that “we do it this way in this project”. And I know myself, that saying that a bunch of times makes it sound like you are being rather anal about how you want the code to look 😅.
Luckily we have tools that save us from that burden. Let’s have a look at what is on offer.
What tools are available to lend a hand?
RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide.
Rubocop is used in Ruby projects. This is the tool that was used when I was doing my pull request on the Faker project. It works by finding offences in your code. Offences being code that does not conform to a standard that is defined in the Rubocop configuration.
JSHint is a community-driven tool that detects errors and potential problems in JavaScript code. Since JSHint is so flexible, you can easily adjust it in the environment you expect your code to execute. JSHint is open source and will always stay this way.
JSHint was my go to linter when I first started building web apps using Javascript. It was easy to integrate into my workflow using npm commands, and saved me from a few rookie mistakes!
You can configure what JSHint checks for using a .jshintrc configuration file. This is handy if you want to add JSHint to an existing project that already has it’s own particular style.
ESLint is an open source project originally created by Nicholas C. Zakas in June 2013. Its goal is to provide a pluggable linting utility for JavaScript.
I remember switching from JSHint to ESLint when I started using ES6 syntax. There are a bunch of configurations you can plug in to ESLint via npm. Some popular ones are:
These configs can be extended quite easily in a .eslintrc configuration file, which enables you to turn comma-dangling off 👀
Pylint is a Python source code analyzer which looks for programming errors, helps enforcing a coding standard and sniffs for some code smells (as defined in Martin Fowler’s Refactoring book).
I don’t use Python regularly, but when I do I like to make sure that I am following standards that are common in the Python community. It is hard to adapt to standards when you don’t read the source code of others on a regular basis.
You can configure this linter using a pylintrc configuration file.
Why is consist code style important?
It enforces all developers working on a project to adapt to the style of your project.
We all have a particular way of writing code, and it would be great to contribute to a project in our own style. But imagine browsing the source code a few months down the line…
I can picture it looking like a mess of:
- Inconsistent syntax
- Variables declared in weird and wonderful ways
- Loops iterated through in different ways
- Functions using a combination of callbacks, promises and async/await syntax
Conclusion
I hope you can take away from this the mindset that coding standards are not there just to make sure that everyone follows the coding style that you have chosen, but that the coding standards are there to help developers that want to contribute to your project.