# Coding Standards

---

**Document Version:** 1.0
**Project:** Student Bazaar
**Document Type:** Development Coding Standards
**Status:** Approved
**Last Updated:** 29 June 2026
**Author:** Nemmi Tangha

---

# 1. Overview

This document defines the coding standards and development practices for Student Bazaar.

All source code generated for the project must follow these standards to ensure consistency, maintainability, readability, and security.

These standards apply to:

* Python
* Flask
* SQLAlchemy
* Jinja2 Templates
* HTML
* CSS
* JavaScript
* MySQL
* Documentation

---

# 2. General Principles

The project follows these development principles:

* Write clean and readable code.
* Keep functions small and focused.
* Follow the Single Responsibility Principle (SRP).
* Avoid duplicate code (DRY).
* Prefer simplicity over unnecessary complexity.
* Keep business logic separate from presentation.
* Write secure code by default.
* Document important functions and classes.

---

# 3. Python Standards

## Style Guide

* Follow **PEP 8**.
* Use 4 spaces for indentation.
* Maximum line length: **88 characters**.
* Use meaningful variable and function names.
* Use type hints where appropriate.

Example:

```python
def create_listing(user_id: int, data: dict) -> Listing:
    ...
```

---

## Naming Conventions

| Item      | Convention | Example                |
| --------- | ---------- | ---------------------- |
| Variables | snake_case | listing_price          |
| Functions | snake_case | create_listing()       |
| Classes   | PascalCase | ListingService         |
| Constants | UPPER_CASE | MAX_IMAGES             |
| Modules   | snake_case | marketplace_service.py |

---

# 4. Flask Standards

Use the Flask Application Factory pattern.

Each feature must use a Blueprint.

Example:

```
app/
    auth/
    marketplace/
    chat/
    negotiation/
    meetup/
    notifications/
    admin/
```

Routes should contain only request handling logic.

Business logic belongs in the Service layer.

Database operations belong in SQLAlchemy models or service classes.

---

# 5. SQLAlchemy Standards

Each table must have:

* Integer primary key
* UUID public identifier
* created_at
* updated_at

Relationships should use SQLAlchemy relationship() definitions.

Avoid raw SQL whenever possible.

Always use parameterized queries.

Use database transactions when multiple related records are modified.

---

# 6. Project Structure

Every module should follow the same structure.

Example:

```
marketplace/

models.py

routes.py

services.py

forms.py

utils.py
```

Each module should remain independent.

Avoid unnecessary dependencies between modules.

---

# 7. HTML Standards

* Use semantic HTML5 elements.
* Maintain proper indentation.
* Avoid inline CSS.
* Avoid inline JavaScript.
* Use Jinja template inheritance.

Example:

```
base.html

↓

dashboard.html
```

---

# 8. CSS Standards

* Use Bootstrap 5 for layout.
* Create custom CSS only when necessary.
* Organize CSS into reusable components.
* Prefer Flexbox and Grid.
* Use CSS variables for colors and spacing.

---

# 9. JavaScript Standards

* Use modern ES6 syntax.
* Prefer `const` and `let`.
* Avoid global variables.
* Separate JavaScript into external files.
* Use descriptive function names.

---

# 10. Security Standards

The application must implement:

* Password hashing using Werkzeug.
* CSRF protection.
* Server-side validation.
* Client-side validation.
* SQL injection prevention.
* XSS prevention.
* Secure file uploads.
* Authentication for protected routes.
* Authorization checks for restricted actions.
* Session security.
* Input sanitization.

Never trust user input.

Always validate data on the server.

---

# 11. Database Standards

* Use foreign keys.
* Maintain referential integrity.
* Use soft deletes where applicable.
* Store timestamps in UTC where practical.
* Avoid redundant columns.
* Normalize the database.

---

# 12. Logging Standards

Log important events, including:

* Login
* Logout
* Registration
* Failed authentication
* Listing creation
* Offer acceptance
* Meet-up completion
* Administrative actions
* Unexpected errors

Sensitive information must never be written to logs.

---

# 13. Error Handling

Use Flask error handlers.

Implement handlers for:

* 400 Bad Request
* 401 Unauthorized
* 403 Forbidden
* 404 Not Found
* 429 Too Many Requests
* 500 Internal Server Error

Display user-friendly error pages.

Log unexpected exceptions.

---

# 14. Documentation Standards

Every module should include:

* Purpose
* Responsibilities
* Dependencies

Complex functions should include docstrings.

Example:

```python
def send_offer():
    """
    Creates a new offer for a listing.

    Parameters:
        listing_id (int)
        sender_id (int)

    Returns:
        Offer
    """
```

---

# 15. Git Standards

Use meaningful commit messages.

Examples:

```
Add marketplace models

Implement chat message limits

Fix notification bug

Update database schema
```

Do not commit:

* .env
* **pycache**
* uploads/
* Temporary files
* API keys

---

# 16. Testing Standards

Test:

* Models
* Services
* Routes
* Authentication
* Forms
* Permissions
* Marketplace
* Chat
* Negotiation

Every critical business rule should have corresponding test cases.

---

# 17. AI-Assisted Development Standards

Claude Code is used as a development assistant.

All generated code must:

* Follow this document.
* Match the approved architecture.
* Match the approved database design.
* Preserve modular architecture.
* Avoid introducing unnecessary dependencies.
* Include comments only where they improve understanding.
* Never change approved business rules without explicit approval.

Generated code should prioritize readability, maintainability, and security over brevity.

---

# 18. Code Review Checklist

Before any feature is considered complete, verify:

* Code follows PEP 8.
* Business logic is in the correct layer.
* Database relationships match the documentation.
* Security checks are implemented.
* Error handling is complete.
* Validation is implemented.
* No duplicated code exists.
* Documentation is updated.
* Tests pass successfully.

---

# 19. Conclusion

These coding standards define the expected quality and structure of the Student Bazaar codebase.

All contributors and AI-assisted development tools must follow these standards throughout the project lifecycle to ensure a secure, maintainable, and scalable application.