目录

Project Overview

Introduction

To ensure the code quality, maintainability, and collaborative efficiency of the FocusFlow project, our team has established and unanimously agreed to adhere to the following code standards. These standards encompass syntax style, engineering practices, and collaboration workflows. They represent a key improvement distilled from our "learning by doing" experience in the Alpha phase.

Part 1: Language-Specific Coding Standards

1. Python (Backend / Scripts)

• Reference: PEP 8.
• Naming:
  • Variables & Functions: snake_case (e.g., calculate_session_duration)
  • Classes: CamelCase (e.g., UserProfileManager)
  • Constants: ALL_CAPS_WITH_UNDERSCORES (e.g., MAX_FOCUS_BLOCK)
• Style:
  • Indentation: 4 spaces.
  • Maximum Line Length: 80 characters.
  • Spacing: Two blank lines between top-level functions/classes. One blank line between methods.
• Documentation:
  • Use docstrings for all modules, classes, and public functions (Google or NumPy style).
  • Use inline comments (#) sparingly for complex logic only.
• Key Practices:
  • Use context managers (with statement) or explicit try...except...finally blocks for resource management (files, DB connections).
  • Always use parameterized queries with the database driver. NEVER use string formatting for SQL statements.
  • Hash passwords using a dedicated library (e.g., bcrypt, passlib) before storage.

2. JavaScript / TypeScript (Frontend - React/React Native)

• Reference: Airbnb JavaScript/React Style Guide (adapted).
• Naming:
  • Variables & Functions: camelCase (e.g., formatTimerDisplay)
  • React Components: PascalCase (e.g., TaskCard, FocusTimer)
  • Constants: ALL_CAPS_WITH_UNDERSCORES for true constants.
• Style:
  • Indentation: 2 spaces.
  • Maximum Line Length: 80 characters.
  • Semicolons: Required.
  • Quotes: Use single quotes (') for strings, backticks (`) for template literals.
• React-Specific:
  • Use functional components with Hooks.
  • Define props and state using TypeScript interfaces or PropTypes.
  • Keep components small and focused on a single responsibility.
• Key Practices:
  • For API calls, use a centralized service (e.g., apiClient.js) built on axios or fetch.
  • Use the useEffect cleanup function to prevent memory leaks (e.g., clear timers, unsubscribe).

3. HTML & CSS

• HTML:
  • Use semantic tags (<header>, <main>, <section>, <article>).
  • Indentation: 2 spaces.
  • Attribute values: Use double quotes (href="...").
• CSS / Styled-Components:
  • Naming: Use the BEM (Block__Element--Modifier) methodology for class names (e.g., .task-card, .task-card__title, .task-card--completed).
  • Organization: Group related properties logically (e.g., Box Model -> Positioning -> Typography -> Visual).
  • Specificity: Avoid !important and overly specific selectors (e.g., div#id .class). Aim for low specificity.

Part 2: Git & Version Control Workflow (CRITICAL)

This section directly addresses a key failure from our Alpha retrospective.

1. Branch Strategy:

   • main: Always deployable. Direct commits are forbidden.
   • develop: Integration branch for features. Most PRs target here.
   • feature/*: Branches for new development (e.g., feature/password-reset, feature/task-cards).
   • hotfix/*: Branches for critical bugs in main.

2. Commit Convention:

   • Format: <type>(<scope>): <subject> (Based on Conventional Commits).
   • Types: feat, fix, docs, style, refactor, test, chore.
   • Example: feat(F1): implement new password reset confirmation screen or fix(F3): align task card layout on mobile.

3. Pull Request (PR) Process:

   • All changes must be introduced via a PR from a feature/hotfix branch.
   • A PR requires at least one approval from a team member other than the author before merging.
   • The PR description must link to the relevant Issue (e.g., Closes #12).
   • The PR must pass the mandatory pre-merge checklist (see Part 3).

Part 3: Pre-Merge Quality Checklist

Before any PR can be merged, the author must confirm the following:

• Code Functionality: The feature/bugfix works as described in the Issue.
• Self-Review: I have reviewed my own code for obvious errors and style violations.
• Linting: Code passes ESLint (for JS/TS) and Flake8/Black (for Python) without errors.
• Testing: For backend logic, corresponding unit tests are added/updated. For frontend components, manual testing has been performed on target devices/browsers.
• No Breaking Changes: The change does not break existing functionality (verified by running the core smoke tests).
• Documentation: Any necessary updates to README, API docs, or inline comments have been made.

Conclusion

These standards are not static rules but a living agreement. They are enforced through peer review in our PR process and serve as our shared foundation for writing clean, secure, and collaborative code. By adhering to them, we aim to eliminate the chaos of the Alpha phase and build FocusFlow into a robust, professional application.