Initial commit. New repo for non-technical documentation
This commit is contained in:
klein panic
176
PoliciesAndStandards/FilePathStandards.md
Normal file
176
PoliciesAndStandards/FilePathStandards.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# File Path Standards
|
||||
|
||||
## Table of Contents
|
||||
1. [Purpose](#purpose)
|
||||
2. [General Directory Structure](#general-directory-structure)
|
||||
3. [Naming Conventions](#naming-conventions)
|
||||
4. [Special Conventions](#special-conventions)
|
||||
5. [Example Directory Structure](#example-directory-structure)
|
||||
6. [Guidelines for Adding New Files](#guidelines-for-adding-new-files)
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document establishes the standards for organizing, naming, and structuring files and directories across all projects within **MidasTechnologies**. Following these guidelines ensures a clean, predictable file layout, making it easy for team members to navigate, understand, and maintain the repository. Clear structure contributes to project scalability, maintainability, and a smoother development experience.
|
||||
|
||||
---
|
||||
|
||||
## General Directory Structure
|
||||
|
||||
The project root directory, **MidasTechnologies**, includes key folders for code, tests, configuration, documentation, and other resources. The layout below provides an organized structure for optimal project navigation and resource management.
|
||||
|
||||
```
|
||||
MidasTechnologies/
|
||||
│
|
||||
├── src/ # Source code for the entire project
|
||||
│ ├── neural-network/ # Neural network-related code
|
||||
│ ├── data-collection/ # Code and data processing tools for data collection
|
||||
│ │ ├── tests/ # Contains unit tests, integration tests, and test resources
|
||||
│ │ └── ... # Additional data collection code modules
|
||||
│ ├── sentiment-analysis/ # Sentiment analysis-related code
|
||||
│ ├── frontend/ # Frontend-related code and assets
|
||||
│ └── ... # Additional modules or features as needed
|
||||
│
|
||||
├── docs/ # All project documentation
|
||||
│ ├── BusinessDocumentation/ # Business-related documentation
|
||||
│ ├── ManPages/ # Global code documentation
|
||||
│ └── PoliciesAndStandards/ # Documentation standards, policies, and guidelines
|
||||
│
|
||||
├── config/ # Configuration files and environment settings
|
||||
├── data/ # Static data files for the entire project
|
||||
├── scripts/ # Utility and setup scripts (e.g., deployment scripts)
|
||||
├── examples/ # Examples and sample code for demonstrating project usage
|
||||
└── assets/ # Static assets (images, icons, etc.) for frontend or docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
1. **File Names**
|
||||
- All file names should be in **lowercase** and use **underscores** to replace spaces (e.g., `data_loader.py`).
|
||||
- Avoid any whitespace, special characters, or symbols. Stick to letters, numbers, and underscores.
|
||||
- If a file is specific to a particular module or feature, use a descriptive prefix or suffix to clarify its purpose, such as `user_model.py`.
|
||||
|
||||
2. **Directory Names**
|
||||
- Directory names should be in **all lowercase** and use hyphens (`-`) to replace spaces (e.g., `user-auth`).
|
||||
- Avoid whitespace and special characters to maintain consistency.
|
||||
- **src/ Directories**: Organize files by functionality, such as `api`, `models`, `services`, `data-collection`, and `utils`.
|
||||
|
||||
3. **Document Files**
|
||||
- **Documentation** should be in **Markdown (.md)** or **Plain Text (.txt)** format.
|
||||
- Documentation filenames should follow a capitalized naming convention (e.g., `README.md` or `GitAndGithubStandards.md`).
|
||||
|
||||
4. **Environment Variables**
|
||||
- Use **all uppercase** with underscores (e.g., `DATABASE_URL`).
|
||||
|
||||
5. **Configuration Files**
|
||||
- Use `.yaml` or `.json` for configuration files to maintain readability and consistency.
|
||||
|
||||
6. **Classes**
|
||||
- Class names should follow **PascalCase** (e.g., `UserService`).
|
||||
|
||||
### GitHub File Naming and Directory Limitations
|
||||
|
||||
When creating or modifying file names and directories, keep in mind GitHub's limitations and best practices:
|
||||
|
||||
- **Character Limit**: File and directory names should not exceed 255 characters.
|
||||
- **Special Characters**: Avoid using special characters (e.g., `@`, `!`, `$`, `%`) as they may cause compatibility issues across different operating systems.
|
||||
- **Case Sensitivity**: GitHub is case-sensitive, so `FilePathStandards.md` and `filepathstandards.md` are treated as distinct files. Use consistent lowercase naming for all files as per our standards.
|
||||
- **Path Depth**: Aim to keep directory nesting shallow to improve readability and reduce navigation complexity.
|
||||
|
||||
Adhering to these guidelines will ensure compatibility across different development environments and maintain uniformity within the repository.
|
||||
|
||||
---
|
||||
|
||||
## Special Conventions
|
||||
|
||||
1. **Documentation Directories**
|
||||
- Documentation directories in `docs/` are an exception to general naming conventions. Documentation files use **Capitalized Names** (e.g., `ManPages`, `BusinessDocumentation`).
|
||||
|
||||
2. **README Files**
|
||||
- Each root module in the project should contain its own `README` file, which provides context and instructions for the specific module.
|
||||
- The `README` file must be in Markdown (`README.md`), Plain Text (`README.txt`), or have no extension (simply `README`).
|
||||
- **Global documentation** for the entire project is held in the `docs/ManPages` directory.
|
||||
|
||||
3. **Test Directories**
|
||||
- All root modules should contain a `tests` directory, located one level deep within the main module folder (e.g., `src/data-collection/tests`). This folder will house unit tests, integration tests, and other test resources relevant to the module.
|
||||
|
||||
4. **Data Directories**
|
||||
- A `data/` directory in the project root holds static data files used across the entire project.
|
||||
- If a `data/` directory exists within a `src` module, it may have specific functionality. Refer to the module’s `README` file for further clarification.
|
||||
|
||||
---
|
||||
|
||||
## Example Directory Structure
|
||||
|
||||
```
|
||||
MidasTechnologies/
|
||||
│
|
||||
├── src/
|
||||
│ ├── neural-network/
|
||||
│ │ ├── models.py # Neural network models
|
||||
│ │ ├── training_script.py # Training scripts
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── data-collection/
|
||||
│ │ ├── data_sources.py # Sources for data collection
|
||||
│ │ ├── process_data.py # Data processing scripts
|
||||
│ │ ├── tests/ # Contains unit tests, integration tests, and test resources
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── sentiment-analysis/
|
||||
│ │ ├── analyze_sentiment.py # Sentiment analysis script
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── frontend/
|
||||
│ │ ├── app.js # Frontend application code
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ └── ...
|
||||
│
|
||||
├── docs/
|
||||
│ ├── README.md # Project overview documentation
|
||||
│ ├── BusinessDocumentation/ # Legal and business-related documentation
|
||||
│ ├── ManPages/ # Global code documentation
|
||||
│ └── PoliciesAndStandards/ # Markdown files on standards, policies, and guidelines
|
||||
│
|
||||
├── config/
|
||||
│ ├── config.yaml # Main project configuration file
|
||||
│ └── dev_config.yaml # Development-specific configuration
|
||||
│
|
||||
├── data/
|
||||
│ └── sample_data.csv # Static data file example
|
||||
│
|
||||
├── scripts/
|
||||
│ ├── setup.sh # Script to initialize the project setup
|
||||
│ └── deploy.sh # Deployment script
|
||||
│
|
||||
├── examples/
|
||||
│ ├── usage_example.py # Example usage of main project features
|
||||
│ └── ...
|
||||
│
|
||||
└── assets/
|
||||
├── logo.png # Project logo
|
||||
└── favicon.ico # Icon for frontend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines for Adding New Files
|
||||
|
||||
1. **Check the Existing Structure**
|
||||
- Review the current directory structure before adding a new file to ensure you place it in the most relevant folder.
|
||||
- Avoid creating redundant or deeply nested directories without a strong rationale.
|
||||
|
||||
2. **Follow Naming Conventions**
|
||||
- Ensure that all files and directories follow the naming conventions specified above, keeping the structure consistent and predictable.
|
||||
|
||||
3. **Document New Directories**
|
||||
- When adding a new folder that doesn’t fit existing patterns, include a `README.md` file or entry in the main project documentation within `docs/` to explain its purpose.
|
||||
|
||||
4. **Requirements for Documentation**
|
||||
- All documentation files should be placed in the appropriate subdirectory within `docs/`.
|
||||
- Markdown or text files should be used for documentation purposes, avoiding other file formats where possible.
|
||||
|
||||
Reference in New Issue
Block a user