DEV Community

Gulnur Baimukhambetova
Gulnur Baimukhambetova

Posted on

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.

Oldest comments (2)

Collapse
 
schemetastic profile image
Rodrigo Isaias Calix

Very interesting suggestions!

Also good quality comments can help a lot, I code in JS too and I find out that JSDoc is a great way to add comments to JS. Not just because adds specificity, but also in VS Code when you hover your pointer over some code elements, it displays a box with data based on those comments. For example:

// Below you can see an example of JSDoc
/**
 * Sums all the numbers
 * @param {Array} numbers The numbers you want to sum
 * @returns {Number} The sum of the array
 */
function sumNumbers(numbers){
    if(!Array.isArray(numbers)) throw TypeError('The `numbers` argument was expected to be an array.');

    let total = 0;
    numbers.forEach((item) => {total += item}); 
    return total;
}
Enter fullscreen mode Exit fullscreen mode

If you copy/paste this in VS Code and then you move your pointer over the function name sumNumbers you should see a box with the data of the comment.

More about this: Documenting JavaScript

Hope this helps!

Collapse
 
gulyapulya profile image
Gulnur Baimukhambetova

Yes, commenting has always been important for making the code more readable. Great suggestion and example!