Good practices that make a difference #1 📝

This is the first post in a series about good practices that I learned during my journey, both at work and in recruiting processes, as well as at college and personal or community projects.

Summary

• 1. Conventions
  • 1.1. File Name
  • 1.2. Name of functions, variables and constants
  • 1.3. Commits
  • 1.4. Branches
• 2. Formatting

1. Conventions

Firstly, we need to understand that a convention is nothing more than any pattern adopted, due to the preferences or needs of a person, team or company.

There are also different conventions depending on the area, stack, or technologies itself, so I'll give examples based on the documentation of the technology I use most at the moment, Next.js, but I strongly advise you to look for the most adopted convention for yours.

1.1. File Name

For both folders and files, kebab-case is most commonly used:

project-name/
├─ src/
│ ├─ app/
│ │ ├─ about-us/
│ │ │ ├─ page.module.css
│ │ │ ├─ page.tsx
│ │ ├─ page.module.css
│ │ ├─ page.tsx
│ ├─ components/
│ │ ├─ ui/
│ │ │ ├─ button.module.css
│ │ │ ├─ button.tsx
│ │ │ ├─ …
│ │ ├─ nav-bar.module.css
│ │ ├─ nav-bar.tsx
│ │ ├─ …
├─ …

1.2. Name of functions, variables and constants

The most common thing that you will find the names of functions, variables and constants in camelCase, except for page functions in which we use PascalCase, and some cases of constants in which we use SCREAMING_SNAKE_CASE.

async function getData() {
  const res = await fetch(process.env.API_URL)
  ...
}

export default function Page() {
  ...
}

1.3. Commits

Here we can go really deep, but let's keep it simple for today.

The most common pattern for the titles of the commits is the type of the change followed by a brief description in the imperative, present simple. As for the description, which is often ignored (I confess that even I fail at this), the ideal is to describe the reason for that change proposed in the commit, and what it does or how it should behave.

E.g.

git commit -m 'feat: add the CTA button'

• feat: <description> for new features;
• fix: <description> for bug fixes;
• chore: <description> for configuration changes, dependencies, etc.;
• refactor: <description> for code refactoring;
• docs: <description> for documentation changes;
• test: <description> for changes to tests;
• style: <description> for style changes;
• ci: <description> for CI/CD changes;
• perf: <description> for performance changes;
• revert: <description> to revert a change;
• merge: <description> for merging branches;
• wip: <description> for work in progress;
• release: <description> for releases;
• config: <description> for configurations;
• build: <description> for build;
• deploy: <description> for deploy;
• remove: <description> for removals;
• add: <description> for additions;
• update: <description> for updates.

1.4. Branches

I intend to go into more detail about the famous Gitflow in the next post, but in general, we have 3 main branches: main, hom for homologation, develop for merging other branches, and in some cases even a fourth called stage.

Similar to commits, branches derived from the develop branch, which we actually work on, often follow the name pattern below:

git branch develop feat/cta-button

• feature/<feature_name> for new features;
• fix/<fix_name> for bug fixes;
• chore/<name_of_change> for changes to configurations, dependencies, etc.;
• refactor/<refactoring_name> for code refactoring;
• docs/<change_name> for changes to documentation;
• test/<test_name> for changes to tests;
• style/<style_name> for style changes;
• ci/<name_of_change> for changes in CI/CD;
• perf/<improvement_name> for performance changes;
• revert/<name_of_change> to revert a change;
• merge/<name_da_alteração> for merging branches.

2. Formatting

The use of Linters and code formatters has become increasingly common, intending to prevent errors and standardize the formatting of the project's code regardless of the team's individual preferences.

The most common on the front end are ESLint and Prettier, and in Python in its various applications, we have tools such as Black, Blue and iSort.

That's it for today, I hope you like it and for any feedback or constructive discussion, see you on social media and here in the comments! 🎉