99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# Project Analysis Methods
|
|
|
|
How to read and understand an unfamiliar code project.
|
|
|
|
## 1. Identify the Entry Point
|
|
|
|
Every project has a door. Find it first.
|
|
|
|
### By Language
|
|
|
|
| Language | Look for |
|
|
|---|---|
|
|
| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
|
|
| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
|
|
| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
|
|
| **Rust** | `src/main.rs` or `src/bin/*.rs` |
|
|
| **Java** | Class with `public static void main(String[] args)` |
|
|
| **C/C++** | `main()` function, conventionally in `src/main.c` |
|
|
| **Swift** | `main.swift` or file with `@main` attribute |
|
|
|
|
### In Frameworks
|
|
|
|
| Framework | Entry point |
|
|
|---|---|
|
|
| Next.js | `app/` or `pages/` directory, `next.config.js` |
|
|
| React (Vite) | `src/main.tsx` or `src/main.jsx` |
|
|
| Vue (Vite) | `src/main.ts` or `src/main.js` |
|
|
| Express | File that calls `app.listen()` |
|
|
| FastAPI | File that creates `FastAPI()` instance |
|
|
| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
|
|
| Flask | `app.py` or `app/__init__.py` |
|
|
| Spring Boot | `*Application.java` with `@SpringBootApplication` |
|
|
|
|
## 2. Judge Project Complexity
|
|
|
|
Don't over-engineer simple projects. Don't under-analyze complex ones.
|
|
|
|
### Simple (<50 files, single language)
|
|
- Read every source file.
|
|
- No need for flow diagrams beyond a simple sequence.
|
|
- A light `/explore` pass is probably enough.
|
|
|
|
### Standard (50-500 files, 1-2 languages)
|
|
- Read entry point + core modules + 1-2 feature files.
|
|
- Build 1-2 flow diagrams.
|
|
- `/explore` is the right level.
|
|
|
|
### Complex (>500 files, multi-language, monorepo)
|
|
- Read entry point + architecture docs + one representative module.
|
|
- Use `/essence` to find standout designs, or `/explore` for one package at a time.
|
|
- Do NOT try to understand the whole project in one pass.
|
|
|
|
## 3. Separate Core Code from Scaffolding
|
|
|
|
Not all files are worth reading.
|
|
|
|
### Ignore (scaffolding)
|
|
- `*.config.js`, `*.config.ts` — configuration, not logic
|
|
- `dist/`, `build/`, `out/` — generated output
|
|
- `node_modules/`, `vendor/`, `.venv/` — dependencies
|
|
- `*.lock`, `yarn.lock`, `go.sum` — lock files
|
|
- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
|
|
- `test/fixtures/`, `test/data/` — test data
|
|
|
|
### Read (core)
|
|
- Entry point file
|
|
- Router/middleware/config handlers
|
|
- Model/entity/schema definitions
|
|
- Core algorithm or business logic files
|
|
- Files referenced most in imports
|
|
|
|
### Hint: Follow imports
|
|
|
|
```
|
|
entry file → import A → import B → core logic
|
|
```
|
|
|
|
Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
|
|
|
|
## 4. Read Unfamiliar Framework Code
|
|
|
|
You don't know every framework. That's fine.
|
|
|
|
### Strategy
|
|
|
|
1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
|
|
|
|
2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
|
|
|
|
3. **Identify the framework's conventions.** Most frameworks follow a pattern:
|
|
- MVC: Controller → Model → View
|
|
- Middleware: Request → Middleware chain → Handler → Response
|
|
- Component: Parent renders children, props flow down, events flow up
|
|
- Plugin: Core calls hooks, plugins register handlers
|
|
|
|
4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
|
|
|
|
5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.
|