feat: Add project directory structure guidelines for maintainability and scalability

This commit is contained in:
William Valentin
2025-08-09 09:11:52 -07:00
parent e42ff9e378
commit 9cec07e9f6

View File

@@ -85,3 +85,32 @@ applyTo: '**'
**Summary:** **Summary:**
This project is a modular, extensible Tkinter application for tracking medication and pathology data. Code should be clean, dynamic, user-friendly, and robust, following PEP8 and the architectural patterns already established. All new features or changes should integrate seamlessly with the existing managers and UI paradigms, unless instructed otherwise. This project is a modular, extensible Tkinter application for tracking medication and pathology data. Code should be clean, dynamic, user-friendly, and robust, following PEP8 and the architectural patterns already established. All new features or changes should integrate seamlessly with the existing managers and UI paradigms, unless instructed otherwise.
**Notes:**
A robust Python project directory structure is crucial for maintainability, scalability, and collaboration. Key best practices include:
Root Project Directory:
Create a top-level directory for your project, typically named after the project itself.
Source Code (src/ or my_package/):
Modern approach: Place all application source code within a src/ directory. This clearly separates source code from other project files.
Alternative: If your project is a single package, the main package directory (e.g., my_package/) can reside directly under the root, containing your modules and __init__.py.
Modularity: Break down your code into smaller, logical modules within this directory, each with a clear responsibility.
__init__.py: Include an __init__.py file in every directory intended to be a Python package, marking it as importable.
Tests (tests/):
Create a dedicated tests/ directory at the root level to house all your test files.
Structure tests to mirror the application's module structure for easier navigation and understanding.
Documentation (docs/):
Include a docs/ directory for project documentation, including usage guides, API references, and design documents.
Configuration (config/ or pyproject.toml):
Use pyproject.toml for modern project configuration, including project metadata, dependencies, and tool configurations (linters, formatters, test runners).
For application-specific or environment-dependent configurations, consider a config/ directory or environment variables.
Entry Point (main.py or cli.py):
Designate a clear entry point for your application, often main.py or cli.py for command-line interfaces. This file should primarily orchestrate the application's flow and delegate logic to other modules.
Other Important Files:
README.md: A comprehensive README at the root level providing project overview, installation instructions, and usage examples.
LICENSE: A license file specifying the terms of use and distribution.
.gitignore: For version control, specifying files and directories to be ignored by Git (e.g., virtual environments, compiled files, sensitive data).
requirements.txt: (or managed via pyproject.toml): Lists project dependencies.
Virtual Environments:
Utilize virtual environments (e.g., venv, conda) to isolate project dependencies and avoid conflicts. The virtual environment directory (e.g., .venv/) should be ignored by version control.