222 lines
5.9 KiB
Markdown
222 lines
5.9 KiB
Markdown
# **Development Experience and Project Specification Organization Document**
|
|
|
|
## Table of Contents
|
|
|
|
1. Variable Name Maintenance Solution
|
|
2. File Structure and Naming Conventions
|
|
3. Coding Style Guide
|
|
4. System Architecture Principles
|
|
5. Core Ideas of Program Design
|
|
6. Microservices
|
|
7. Redis
|
|
8. Message Queue
|
|
|
|
---
|
|
|
|
# **1. Variable Name Maintenance Solution**
|
|
|
|
## 1.1 Create a "Comprehensive Variable Name File"
|
|
|
|
Establish a unified variable index file for AI and overall team maintenance.
|
|
|
|
### File content includes (format example):
|
|
|
|
| Variable Name | Variable Comment (Description) | Location (File Path) | Frequency (Statistics) |
|
|
| :------------ | :----------------------------- | :------------------------- | :--------------------- |
|
|
| user_age | User age | /src/user/profile.js | 12 |
|
|
|
|
### Purpose
|
|
|
|
* Unified variable naming
|
|
* Convenient global search
|
|
* AI or human can uniformly manage and refactor
|
|
* Reduce the risk of naming conflicts and unclear semantics
|
|
|
|
---
|
|
|
|
# **2. File Structure and Naming Conventions**
|
|
|
|
## 2.1 Subfolder Content
|
|
|
|
Each subdirectory needs to contain:
|
|
|
|
* `agents` - Responsible for automation processes, prompts, agent logic
|
|
* `claude.md` - Stores documentation, design ideas, and usage for the content of this folder
|
|
|
|
## 2.2 File Naming Rules
|
|
|
|
* Use **lowercase English + underscore** or **camelCase** (depending on the language)
|
|
* Filenames should reflect content responsibilities
|
|
* Avoid abbreviations and ambiguous naming
|
|
|
|
Examples:
|
|
|
|
* `user_service.js`
|
|
* `order_processor.py`
|
|
* `config_loader.go`
|
|
|
|
## 2.3 Variable and Definition Rules and Explanations
|
|
|
|
* Naming should be as semantic as possible
|
|
* Follow English grammatical logic (noun attributes, verb behaviors)
|
|
* Avoid meaningless names like `a, b, c`
|
|
* Constants use uppercase + underscore (e.g., `MAX_RETRY_COUNT`)
|
|
|
|
---
|
|
|
|
# **3. Coding Style Guide**
|
|
|
|
### 3.1 Single Responsibility
|
|
|
|
Each file, class, and function should be responsible for only one thing.
|
|
|
|
### 3.2 Reusable Functions / Constructs (Reusable Components)
|
|
|
|
* Extract common logic
|
|
* Avoid duplicate code (DRY)
|
|
* Modularize, functionalize, and improve reuse value
|
|
|
|
### 3.3 Consumer / Producer / State (Variables) / Transformation (Functions)
|
|
|
|
System behavior should be clearly divided:
|
|
|
|
| Concept | Description |
|
|
| :------------------- | :---------------------------------------- |
|
|
| Consumer | Where external data or dependencies are received |
|
|
| Producer | Where data is generated and results are output |
|
|
| State (Variables) | Variables storing current system information |
|
|
| Transformation (Functions) | Logic for processing states and changing data |
|
|
|
|
Clearly distinguish **Input → Process → Output** and manage each stage independently.
|
|
|
|
### 3.4 Concurrency
|
|
|
|
* Clearly distinguish shared resources
|
|
* Avoid data races
|
|
* Use locks or thread-safe structures when necessary
|
|
* Distinguish between "concurrent processing" and "asynchronous processing"
|
|
|
|
---
|
|
|
|
# **4. System Architecture Principles**
|
|
|
|
### 4.1 First Clarify the Architecture
|
|
|
|
Before writing code, clarify:
|
|
|
|
* Module division
|
|
* Input/output
|
|
* Data flow
|
|
* Service boundaries
|
|
* Technology stack
|
|
* Dependencies
|
|
|
|
### 4.2 Understand Requirements → Keep It Simple → Automated Testing → Small Iterations
|
|
|
|
Rigorous development process:
|
|
|
|
1. First understand the requirements
|
|
2. Keep architecture and code simple
|
|
3. Write maintainable automated tests
|
|
4. Iterate in small steps, avoid big-bang development
|
|
|
|
---
|
|
|
|
# **5. Core Ideas of Program Design**
|
|
|
|
## 5.1 Start from the problem, not from the code
|
|
|
|
The first step in programming is always: **What problem are you solving?**
|
|
|
|
## 5.2 Break large problems into small problems (Divide & Conquer)
|
|
|
|
Decompose complex problems into small, independently achievable units.
|
|
|
|
## 5.3 KISS Principle (Keep It Simple, Stupid)
|
|
|
|
Reduce complexity, magic code, obscure tricks.
|
|
|
|
## 5.4 DRY Principle (Don't Repeat Yourself)
|
|
|
|
Reuse logic with functions, classes, modules; don't copy-paste.
|
|
|
|
## 5.5 Clear Naming
|
|
|
|
* `user_age` is clearer than `a`
|
|
* `get_user_profile()` is clearer than `gp()`
|
|
Naming should reflect **purpose** and **semantics**.
|
|
|
|
## 5.6 Single Responsibility
|
|
|
|
A function handles only one task.
|
|
|
|
## 5.7 Code Readability First
|
|
|
|
The code you write is for others to understand, not to show off.
|
|
|
|
<h2>5.8 Appropriate Comments</h2>
|
|
|
|
Comments explain "why," not "how."
|
|
|
|
## 5.9 Make it work → Make it right → Make it fast
|
|
|
|
First make it run, then make it beautiful, then optimize performance.
|
|
|
|
## 5.10 Errors are friends, debugging is a mandatory course
|
|
|
|
Reading errors, checking logs, and tracing layers are core programmer skills.
|
|
|
|
## 5.11 Git version control is essential
|
|
|
|
Never keep code only locally.
|
|
|
|
## 5.12 Test your code
|
|
|
|
Untested code will eventually have problems.
|
|
|
|
## 5.13 Programming is long-term practice
|
|
|
|
Everyone has experienced:
|
|
|
|
* Can't debug a bug
|
|
* Feeling like striking gold when it passes
|
|
* Eventually understanding others' code
|
|
|
|
Persistence makes one an expert.
|
|
|
|
---
|
|
|
|
# **6. Microservices**
|
|
|
|
Microservices are an architectural pattern that breaks down a system into multiple **independently developed, independently deployed, and independently scalable** services.
|
|
|
|
Characteristics:
|
|
|
|
* Each service handles a business boundary (Bounded Context)
|
|
* Services communicate via APIs (HTTP, RPC, MQ, etc.)
|
|
* More flexible, more scalable, higher fault tolerance
|
|
|
|
---
|
|
|
|
# **7. Redis (Cache / In-memory Database)**
|
|
|
|
The role of Redis:
|
|
|
|
* Greatly improves system "read performance" as a cache
|
|
* Reduces database pressure
|
|
* Provides capabilities such as counters, locks, queues, sessions
|
|
* Makes the system faster, more stable, and more resilient
|
|
|
|
---
|
|
|
|
# **8. Message Queue**
|
|
|
|
Message queues are used for "asynchronous communication" between services.
|
|
|
|
Purpose:
|
|
|
|
* Decoupling
|
|
* Peak shaving and valley filling
|
|
* Asynchronous task processing
|
|
* Improve system stability and throughput
|