Code style guide

This page explains the project's code quality expectations in beginner-friendly language.

The goal is not perfect code. The goal is readable, maintainable code that other contributors can understand and review.

Keep changes small

Small changes are easier to review and easier to fix. A good pull request should usually do one thing:

• fix one bug
• add one feature
• improve one part of the documentation
• clean up one focused area

Avoid mixing unrelated changes in the same pull request.

Use readable names

Choose names that explain what something is or does.

Good names:

• product_name
• sell_price
• buy_price
• product_id

Avoid names that are too short or unclear, unless the meaning is obvious.

Naming conventions

• Functions: snake_case
• Classes: PascalCase
• Indentation: 4 spaces

Match what is already in the project.

Avoid unrelated refactoring

Do not rewrite or reorganize code unless it is part of the issue you are solving. Unrelated refactoring makes pull requests harder to review.

If you notice cleanup that should be done later, open a separate issue.

Run Ruff

We use Ruff for formatting and linting.

Install Ruff:

pip install -r requirements.txt

Or directly:

pip install ruff

Using Ruff

Format your code:

ruff format .

Check for issues:

ruff check .

Fix issues automatically:

ruff check --fix .

Only format files that are part of your change.

Setting up Ruff in your editor

VS Code - Install the Ruff extension and add this to your settings:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

Zed - Ruff is the default formatter for Python. No setup needed.

PyCharm - Install the Ruff plugin:

1. Go to Settings -> Plugins and search for "Ruff".
2. Install and restart PyCharm.
3. Go to Settings -> Tools -> Ruff.
4. Check Enabled and set Run on save to true.
5. PyCharm will auto-detect the project's ruff.toml.

The project's ruff.toml file keeps formatting the same across all editors.

Remove debug prints

Temporary print statements are useful while developing, but remove them before opening a pull request. Do not leave debug output unless it is part of the intended user experience.

Write helpful comments only when needed

Comments should explain why something is done, not repeat what the code already says.

Helpful comment:

# Keep this check before saving so invalid products never reach the database.

Less useful comment:

# Set name to product_name.

Avoid leaving commented-out code. If it is not used, delete it.

Keep functions focused

A function should usually have one clear purpose. If a function becomes long or hard to understand, consider whether part of it should move into a helper function.

Do not split code just to split it. Split code when it becomes easier to read or test.

Handle user input carefully

The app runs in the terminal, so users may type unexpected things. Think about:

• empty input
• wrong type of input
• negative numbers
• unknown commands
• IDs that do not exist

The app should give a useful message and keep running when possible.

Pull request quality checklist

Before opening a pull request, check:

• the change solves the linked issue
• the pull request is focused
• the app still starts
• the changed behavior was tested manually
• Ruff has been run
• debug prints are removed
• data/products.db is not included
• the pull request description explains what changed

Good code is not just code that works. It is code the team can understand, review, and safely build on.