How to beautify your code and make contributions easy?

Hello everyone! 🙋🏻‍♀️

Today, I learned about Static Analysis tools which work on increasing the quality of your source code from the formatting and styling perspectives and by identifying bad coding practices.

I added multiple tools to my SSGulnur project and below I will explain why they you probably need them too.

Code formatters 💄

In open source, most of the projects use automatic source code formatters, beautifiers or "pretty printers". They make contributing easier, as they keep the source code in a consistent format.

I am using mostly JavaScript, so my obvious choice was Prettier. For most of the formatters, the steps are similar such as you would have to:

1. read through the documentation to install and setup the tool,
2. configure the rules and options to customize the look, e.g., .prettierrc
3. create an ignore file to exclude files from formatting, e.g., .prettierignore,
4. (optional but great to do) create a script to run the formatter in one command, e.g., npm run prettier defined as a script in package.json .

Linters 🕵️‍♂️

While contributing to a project, the least a develop wants to do is add code full of little bugs and bad practices. Linters help with that problem by scanning the sources code and identifying syntax errors, adherence to coding standards, security bugs and other potential errors.

For my project, the best choice is ESLint as it is widely used. The steps are very similar to adding a beautifier.

Editor 📠

The same way we configure our local editors, we can also pre-set the IDE settings for everyone who downloads the project. In VSCode, you can configure workspace setting which override the user's settings. Also, VSCode has lots of extensions and the ones for Prettier and ESLint which make the development much easier. There is a way to set extension recommendations for a workspace.

Pre-commit hook 🛃

Additionally, there are pre-commit hooks which can be setup to seamlessly validate and modify the source code before every commit. I followed Prettier documentation to create one. I ran npx mrm@2 lint-staged which installed husky and lint-stagedand added a configuration to the project’s package.json. Then, I modified the commands a little and that's it.

CONTRIBUTING.md 📜

Creating a CONTRIBUTING.md file is very important if you want other people to contribute to your project as it will be the first stop guide which should explain how to choose issues, set-up a tool, test it, any conventions and other development instructions.

Conclusion 💡

Let the tools do the work for you!

Ps:

Yesterday, one of my classmates shared an interesting article which encourages people to blog and brings up a few blogging ideas. The author, Simon Willison, believes that one of the best topics to chose is TIL which means "Today I Learned". It reminded me so much of all these posts which I used to start with "Today, I explored/tried/coded/learned/etc.". However, before my article name convention was "My first " + topic name. Recently, I realized that what I write is much more meaningful than "just my first experience", so I should not limit the name. From now on, my blogs will most probably start with "How " + my actions. They will not be fully detailed documentations but should describe the main ideas around the topic and steps.