Style Guide

Introduction

This style guide aims to provide guidelines for writing and organizing code within our project.

Directory Structure

Python Files

Python modules/files must be placed directly inside the app/ directory. Write your functions inside the relevant file such as app.py for Flask routes, utils.py for utility functions, etc. If you are developing a large feature, you can create a new module for better organisation of the codebase.

project
├─ app
   ├─ app.py
   ├─ extract_text.py
   ├─ utils.py
   ├─ web_cli.py

JavaScript Files:

All JavaScript files must be placed within the app/static/js directory. Subdirectories within app/static/js should be created for organization when necessary, typically grouping related functionalities (e.g., user, dashboard).

project
├─ app
├─ static
├─ js
├─ hotkeys.js
├─ mediaControls.js
├─ otherControls.js
├─ webCli.js

Code Style

Python Code:

• Follow PEP 8 -- Style Guide for Python Code.
• Use 4 spaces for indentation.
• Limit all lines to a maximum of 120 characters.
• Use docstrings and comments where appropriate for function and module descriptions.
• Ensure functions are not overly complex and messy. Split functions into multiple if necessary.

Jinja2 Templates:

• Indentation should be consistent and aligned with HTML structure.
• Logic and control structures in templates should be minimized.
• Reuse and include or extend templates to avoid duplication.

JavaScript:

• Use ES6 syntax and features.
• Prefer const and let over var.
• Use camelCase for variable names and functions.
• Use PascalCase for class names.
• Avoid inline JavaScript in Jinja2 templates when possible; use separate files in the app/static/js directory.

Unit Testing

All new features must be accompanied by corresponding unit tests. Tests should be written using the pytest module. Aim for a high code coverage percentage to ensure robustness. Create new unit test files if you created a new python file when developing your feature, otherwise write your tests in the test file where you developed your code. Test files should be placed in the tests directory and follow the naming convention: test_module_name.py

Commit Messages

• Commit messages MUST provide a clear and concise description of the changes made.
• Commit messages MUST NOT be based solely on the issue number.