Skip to content
This repository has been archived by the owner on Feb 20, 2023. It is now read-only.

Advanced Setup

Jump to bottom
aedwardg edited this page Feb 26, 2021 · 1 revision

Advanced Setup (optional)

This document applies to the project features implemented by PR #76 as part of the push to enforce uniform code standards for the Dwellingly backend. Any additional setup instructions referenced here are completely optional, but are worth the extra step if you feel comfortable doing so.

Table of Contents

Introduction

We recently introduced strict linting and formatting requirements for all code being added to the Codecademy Discord Bot repo. This is accomplished through a combination of:

As the name suggests, the pre-commit hook will do the following before your commit is processed:

  • Check for the required newline at the end of every file (will auto-fix)
  • Check for trailing whitespace on all lines of every file (will auto-fix)
  • Check JavaScript and Markdown files for compliance with Prettier formatting (will auto-fix if possible)
  • Check JavaScript files for compliance via any of ESLint's recommended rules and Google's ESLint rules that do not conflict with Prettier (will auto-fix if possible)

If any of these checks don't pass, your commit will be aborted — even if your files were auto-fixed by the pre-commit hook.

Occasionally, ESLint will not be able to auto-fix problems with your code. In that case, you will need to make that fix manually. All ESLint errors will show in the console, along with the line number, column and ESLint rule.

Once all changes have been made (by you or by automation), you must git add and git commit again. If everything was properly resolved, your commit will be successful.

This sounds painful, is it even worth it?

Yes, absolutely.

The pre-commit hook will ensure that no matter which contributor wrote the code, all JavaScript in the repo will be formatted the same way. Some advantages include:

  • Faster review:
    • All the code will look similar, with no personal quirks or strange styling hold-overs from other languages. This makes it faster to read, comprehend and give feedback on newly added code.
    • Git diffs will be smaller and clearer because Prettier tends to make the code more vertical. Vertical code means there won't be a gigantically long diff when, e.g., one item in a list gets changed.
  • Faster time to merge:
    • Gone are the days of being asked to add a newline or a semicolon before your PRs can be merged. The pre-commit takes care of this for you before the reviewer ever sees your code.
  • Closer to production ready:
    • We currently push to production very shortly after changes are committed to the development branch. Because of this, it is especially important that we catch and resolve as many syntax-related errors as possible before our code gets merged. ES Lint and Prettier will catch more (and faster) than we could with manual reviews.

It is also important to recognize that you don't have to go blindly into your commit, hoping to pass the tests. The pre-commit hook is the enforcer, but the real power behind linters and formatters comes through using them as you write your code, not only at the end.

The following sections contain instructions on using ESLint and Prettier on the command line as well and links on how to set these up for automatic use with a variety of IDEs and code editors. Git Blame is also mentioned, as it is a useful tool when working on teams and requires some special set-up since we migrated to Prettier code style a little late in the project.

ESLint

ESLint lints your JavaScript files, letting you know if you have any problems with your code or if your code does not pass ESLint's recommended rules or Google's ESLint rules. If it detects problems with your code, ESLint can try to fix them for you, but there will be times you have to fix linting errors yourself. You can lint your code periodically from the command line, or set up your editor to do it for you by following the instructions below.

ESLint Command Line Usage

Run the following command from the codecademy-discord-bot directory to lint all JavaScript files in the repo (without auto-fixing errors):

npx eslint .

If you would like ESLint to try to auto-fix errors it finds during linting, you can pass it the --fix flag:

npx eslint --fix .

You can also narrow the scope of your linting by passing in the path for the directory or file you want to lint:

npx eslint {path_to_dir_or_file}

If you need more advanced options, check out the ESLint CLI documentation.

Use ESLint in Your Editor

For even more instantaneous linting, you can also set up ESLint with most IDEs and code editors.

Every editor is configured differently, so if your editor of choice isn't listed, a quick Google search may be needed. Please add documentation links to this list if you successfully integrate ESLint with an editor not listed here!

Prettier

Prettier is a code formatter that formats JavaScript files (and more) according to very opinionated styling rules. When Prettier is run, it will check your file(s) and if it decides changes are needed, it will re-format your code to the best of its abilities. This will never change the substance of your code, only the styling. Occasionally, Prettier will not be able to auto-format part of your code (such as extra long strings or comments) and you will need to make those changes manually if you want them to conform to a certain line length.

Prettier Command Line Usage

Run the following command from the codecademy-discord-bot directory to format all JavaScript and Markdown files in the repo using Prettier:

npx prettier --write .

If you would like to check the files comply with Prettier (without auto-formatting them) you can instead use the --check flag:

npx prettier --check .

To format only a specific file or directory, you simply specify the path, as you would with ESLint:

npx prettier --write {source_file_or_directory}

For advanced command line options, see the Prettier documentation.

Use Prettier in Your Editor

One of the best features of code formatters is that you can set them up to format on save with your editor. Once set up, every time you save your file, Prettier will auto-format the code you wrote. This is a no-brainer way to fix your code before commit time.

  • Most Editors:
    • The Prettier documentation has a fairly extensive section on editor integration. Follow those instructions, and if your editor is not listed, consider opening up an issue on their GitHub page.

Git Blame

Git blame is a built-in feature of Git that allows you to see the most recent commit and author that changed any given line of code in a file. Git blame can be incredibly useful on team projects because if you find a bug or don't understand a certain section of the code, you can reach out to the original author or read the commit messages where the code was added.

Cleansing the Git Blame

One unfortunate side effect of migrating to Prettier code style late in a project's lifecycle is that the initial re-formatting of the files will pollute the git blame. Essentially, most lines of most files will blame the author of the commit that did the re-formatting rather than the last person who really changed the code.

If you want to use Git Blame for this project, you should tell Git to ignore the re-formatting commit by running the following command from inside the codecademy-discord-bot directory:

git config blame.ignoreRevsFile .git-blame-ignore-revs

After this command is run, lines modified by backend PR #185 will be blamed on the previous revision that modified those lines.

Git Blame Command Line Usage

To use Git blame on the command line, it's as simple as running this command:

git blame {path_to_file}

You will see the blame annotations in your terminal and you can navigate through them using the up and down arrows. To exit the blame, press q. If you are familiar with using the git log command, this will be familiar to you.

For advanced command line options, see the git documentation.

Git Blame in Your Editor

Where Git blame really shines is in the interactive extensions for various code editors — VS Code in particular. These extensions have awesome features that range from color-coded revisions to in-line annotations and GitHub integration. Below are examples for some editors we use.

Every editor has different extensions, so if your editor of choice isn't listed, a quick Google search may be needed. Please add documentation links to this list if you find an awesome Git blame extension for an editor not listed here!

Clone this wiki locally