# Naming Conventions Guide

This document establishes naming standards for the Ghidra MCP project to ensure consistency and maintainability.

---

## Markdown Files

### Root-Level Documentation (UPPERCASE)
All primary markdown files in the root directory use **UPPERCASE** for visibility and discoverability:

```
README.md                    — Main project overview and getting started
CHANGELOG.md                 — Version history and release notes
CONTRIBUTING.md              — Contribution guidelines and development setup
LICENSE                      — Project license (no extension)
START_HERE.md                — Quick start guide for new users
INSTALLATION.md              — Setup and installation instructions (future)
SECURITY.md                  — Security guidelines and reporting (future)
```

**Rationale**: 
- UPPERCASE files stand out in file listings
- GitHub automatically renders `.md` files
- Consistent with industry standards (Python, Node.js, etc.)

### Documentation Folder (`docs/`)
Organized reference documentation also uses **UPPERCASE**:

```
docs/TOOL_REFERENCE.md           — Authoritative endpoint catalog (243 tools)
docs/ERROR_CODES.md              — Error catalog and troubleshooting guide
docs/PERFORMANCE_BASELINES.md    — Performance metrics and optimization
docs/ARCHITECTURE.md             — System architecture and design
docs/API.md                      — API overview and integration guide
docs/EXAMPLES.md                 — Example workflows and use cases
```

**Rationale**:
- Easy to find reference documentation
- Consistent naming across docs folder
- Self-documenting purpose from filename

### Project Management Files
Status tracking and organization files:

```
IMPROVEMENTS.md                  — Improvement roadmap and feature tracking
PROJECT_STATUS.md                — Current project status (replaces dated reports)
QUICKWIN_CHECKLIST.md            — Quick win task tracking
```

**Rationale**:
- Clear that these are project-level documents
- Centralized status tracking

---

## Java Code

### File Naming (PascalCase)
Java files use **PascalCase** matching the public class name:

```java
✅ GOOD
GhidraMCPPlugin.java          — Main plugin entry point
ToolRegistry.java             — Tool registration system
MCSProtocolHandler.java       — Protocol implementation

❌ AVOID
GhidraMcpPlugin.java
ghidra_mcp_plugin.java
Ghidra-MCP-Plugin.java
```

### Class Naming (PascalCase)
```java
public class GhidraMCPPlugin { }           ✅
public class ToolRegistry { }               ✅
public class MCSProtocolHandler { }         ✅
```

### Method Naming (camelCase)
```java
public void registerTool() { }              ✅
private String getToolName() { }            ✅
protected void parseRequest() { }           ✅
```

### Constant Naming (UPPER_SNAKE_CASE)
```java
public static final String VERSION = "1.9.2";        ✅
public static final int MAX_BATCH_SIZE = 100;        ✅
private static final long TIMEOUT_MS = 5000L;        ✅
```

### Variable Naming (camelCase)
```java
String toolName = "decompile";             ✅
int maxRetries = 3;                        ✅
boolean isEnabled = true;                  ✅
```

---

## Python Code

### File Naming (snake_case)
Python files use **snake_case** following PEP 8:

```
✅ GOOD
analyze_functions.py
create_struct_workflow.py
library_code_detector.py
ordinal_auto_fixer.py

❌ AVOID
AnalyzeFunctions.py
analyze-functions.py
Analyze_Functions.py
```

### Function Naming (snake_case)
```python
def get_function_xrefs():                   ✅
def batch_rename_functions():               ✅
def extract_ioc_strings():                  ✅
```

### Class Naming (PascalCase)
```python
class GhidraBridge:                         ✅
class ToolRegistry:                         ✅
class MCPServer:                            ✅
```

### Constant Naming (UPPER_SNAKE_CASE)
```python
DEFAULT_TIMEOUT = 300                       ✅
MAX_BATCH_SIZE = 100                        ✅
API_VERSION = "1.0"                         ✅
```

### Variable Naming (snake_case)
```python
tool_name = "decompile"                     ✅
is_enabled = True                           ✅
max_retries = 3                             ✅
```

---

## Command-Line Utilities

### Python Utility Naming
Project-specific command-line utilities should be Python modules or
snake_case Python scripts.

```
✅ GOOD
fun_doc.py
ordinal_auto_fixer.py
inventory_scorer.py
```

The bridge itself is now a package (`python/bridge_mcp_ghidra/`) exposed as
the `bridge-mcp-ghidra` console script / `python -m bridge_mcp_ghidra`.

### Environment-Native Wrappers
Generated or environment-specific launchers may still exist where required by
the platform or toolchain, but they are not the preferred place for project
logic. Examples include container entrypoints and generated build-tool wrappers.

---

## Configuration Files

### Format: lowercase with dots
```
.mcp.json                     — MCP server configuration (Claude Code auto-discovery)
pyproject.toml                — Python build, dependencies, and test configuration
.gitignore                    — Git ignore rules
.env.template                 — Environment variable template
```

### Maven Configuration (root)
```
pom.xml                       — Maven project file (standardized)
```

---

## Log and Temporary Files

### Log Files (snake_case with timestamps)
```
ordinal_fix_log_20251105_120000.txt        — Process logs with timestamp
build.log                                   — Build output
test_results.log                            — Test output
```

**Format**: `process_type_log_YYYYMMDD_HHMMSS.txt`

### Temporary/Archive Files
```
logs/                         — Archive old logs here
archive/                      — Store completed reports here
.backups/                     — Backup files (gitignored)
```

---

## Directory Structure

### Standard Layout (recommended)
```
ghidra-mcp/
├── README.md                 — Project overview
├── CONTRIBUTING.md           — Contribution guide
├── CHANGELOG.md              — Version history
├── docs/
│   ├── TOOL_REFERENCE.md
│   ├── ERROR_CODES.md
│   ├── PERFORMANCE_BASELINES.md
│   └── ARCHITECTURE.md
├── examples/
│   ├── README.md
│   ├── analyze_functions.py
│   ├── create_struct_workflow.py
│   └── ...
├── src/
│   ├── main/java/
│   │   └── com/xebyte/
│   │       ├── GhidraMCPPlugin.java
│   │       ├── ToolRegistry.java
│   │       └── ...
│   └── test/java/
│       └── com/xebyte/
│           └── GhidraMCPPluginTest.java
├── tools/
│   ├── setup/
│   └── README.md   # points at fun-doc/ for documentation CLI
├── logs/
│   └── (archived logs here)
└── ...
```

---

## Quick Reference

| Type | Standard | Example | Rationale |
|------|----------|---------|-----------|
| **Markdown (root)** | UPPERCASE | `README.md` | Visibility, GitHub convention |
| **Markdown (docs)** | UPPERCASE | `TOOL_REFERENCE.md` | Organization, consistency |
| **Java files** | PascalCase | `GhidraMCPPlugin.java` | Java convention |
| **Java classes** | PascalCase | `class ToolRegistry` | Java convention |
| **Java methods** | camelCase | `getTool()` | Java convention |
| **Java constants** | UPPER_SNAKE_CASE | `MAX_SIZE` | Java convention |
| **Python files** | snake_case | `analyze_functions.py` | PEP 8 convention |
| **Python classes** | PascalCase | `class GhidraBridge` | PEP 8 convention |
| **Python functions** | snake_case | `get_xrefs()` | PEP 8 convention |
| **Python constants** | UPPER_SNAKE_CASE | `API_VERSION` | PEP 8 convention |
| **Python utilities** | snake_case | `inventory_scorer.py` | PEP 8 convention |
| **Config files** | lowercase.ext | `.mcp.json` | Convention |
| **Logs** | snake_case_date | `build_log_20251105.txt` | Readability |

---

## Enforcement

### GitHub Actions
Add to CI/CD pipeline (when implemented):
- **Python**: `flake8` and `black` enforce snake_case naming
- **Java**: `checkstyle` enforces Java naming conventions

### Pre-commit Hooks (future)
Use pre-commit or CI checks to validate Markdown, Python, and Java naming
conventions.

---

## Migration Plan

For existing files that don't follow conventions:

| Current | Recommended | Action | Priority |
|---------|-------------|--------|----------|
| `CLAUDE.md` | `ARCHITECTURE.md` | Rename when restructuring | Low |
| `ordinal_fix_log_*.txt` | Archive to `logs/` folder | Organize existing logs | Low |
| Old reports | Archive or consolidate | Move to `archive/` | Low |
| Examples `.py` files | Already `snake_case` ✅ | No action | — |
| Docs in `docs/` | Already `UPPERCASE` ✅ | No action | — |

---

## References

- [Python PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/)
- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
- [GitHub's Naming Conventions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
- [Markdown Best Practices](https://www.markdownguide.org/basic-syntax/)

---

**Last Updated**: November 5, 2025  
**Version**: 1.0
