For Contributors Coding Standards

🔧 Coding Standard

All team members must adhere to the following coding conventions to ensure consistent style, readability, and maintainability.

---

1. Naming Conventions

Type	Style	Example
Variables	snake_case	user_data
Functions	snake_case	get_user_data()
Class Names	PascalCase	UserManager
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT
Module/Filenames	snake_case	user_service.py

• Names should be concise and descriptive. Avoid meaningless abbreviations like temp, data1, etc.
• Boolean names should use prefixes like is_, has_, can_: is_active, has_permission.

---

2. Code Formatting

Indentation

• Use 4 spaces per indentation level (no tabs)
• All code blocks (functions, conditionals, loops) must be properly indented

Brackets and Spaces

• No space before parentheses in function calls/declarations: func(x), not func (x)
• Operators should have spaces: a + b, not a+b

Line Length

• Maximum line length of 100 characters
• Break long expressions with proper indentation

---

3. Commenting Guidelines

Single-line Comments

• Use # for concise, clear comments

  # Initialize user data
  user = User()

Docstrings

• All functions, classes, and modules must have docstrings using triple quotes (""")

  def get_user(user_id: int) -> User:
      """
      Retrieve user object by ID.
  
      Args:
          user_id (int): Unique identifier for user
  
      Returns:
          User: Corresponding user object
  
      Raises:
          UserNotFoundError: If no user exists with given ID
      """
      ...

---

4. Code Organization

General order within each module/file:

1. Imports (standard library -> third-party -> local modules)
2. Constant definitions
3. Class/function definitions
4. Main logic (e.g., if __name__ == "__main__":)
5. Test code (if present)

---

5. Error Handling

• Use try-except blocks for potential errors
• Catch specific exceptions, avoid bare except clauses
• Log errors for debugging

try:
    result = fetch_data()
except ConnectionError as e:
    logger.error(f"Connection failed: {e}")

---

6. Git Commit Standard

Commit messages should follow this format:

<type>(<scope>): <brief description>

Examples:

• feat(auth): add OAuth2 login support
• fix(ui): resolve button alignment issue
• docs(readme): update usage instructions

Common types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Formatting changes (no logic change)
• refactor: Code refactoring
• test: Test additions/modifications
• chore: Maintenance tasks (build tools, etc.)

---

7. Code Quality Tools

• All commits must pass static analysis (flake8, pylint)
• Recommended tools:
  • Formatting: black, isort
  • Linting: flake8, mypy (for type checking)

---

8. References

• For Contributors Resource References
• PEP 8 - Python Style Guide
• Google Python Style Guide
• Conventional Commits