mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-25 08:38:17 +00:00
feat(en): translate missing documents using Gemini CLI
- Add Common Pitfalls.md (常见坑汇总) - Add Language Layer Elements.md (语言层要素) - Add External Resource Aggregation.md (外部资源聚合) - Remove empty placeholder directories - Remove duplicate gluecoding.md from zh - Update README files
This commit is contained in:
tukuaiai
@@ -0,0 +1,477 @@
|
||||
# 🕳️ Common Pitfalls Summary
|
||||
|
||||
> Common issues and solutions during the Vibe Coding process
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🤖 AI Chat Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| AI generated code doesn't run | Insufficient context | Provide full error messages, describe the runtime environment |
|
||||
| AI repeatedly modifies the same issue | Stuck in a loop | Describe with a different approach, or start a new conversation |
|
||||
| AI hallucinating, fabricating non-existent APIs | Outdated model knowledge | Provide official documentation links for AI reference |
|
||||
| Code becomes messy with changes | Lack of planning | Let AI propose a plan first, then write code after confirmation |
|
||||
| AI doesn't understand my requirements | Vague description | Explain with concrete examples, provide input and output samples |
|
||||
| AI forgets previous conversations | Context loss | Re-provide key information, or use a memory bank |
|
||||
| AI modifies unintended code | Unclear instructions | Explicitly state "only modify xxx, do not touch other files" |
|
||||
| AI generated code style is inconsistent | No style guide | Provide a code style guide or sample code |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🐍 Python Virtual Environment Related</strong></summary>
|
||||
|
||||
### Why use a virtual environment?
|
||||
|
||||
- Avoid dependency conflicts between different projects
|
||||
- Keep the system Python clean
|
||||
- Easy to reproduce and deploy
|
||||
|
||||
### Creating and using .venv
|
||||
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python -m venv .venv
|
||||
|
||||
# Activate virtual environment
|
||||
# Windows
|
||||
.venv\Scripts\activate
|
||||
# macOS/Linux
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Deactivate virtual environment
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Cannot configure environment at all | Global pollution | Delete and restart, use `.venv` for virtual environment isolation |
|
||||
| `python` command not found | Virtual environment not activated | Run `source .venv/bin/activate` first |
|
||||
| Package installed but import error | Installed globally | Confirm virtual environment is activated before `pip install` |
|
||||
| Dependency conflicts in different projects | Sharing global environment | Create a separate `.venv` for each project |
|
||||
| VS Code uses wrong Python | Interpreter not selected correctly | Ctrl+Shift+P → "Python: Select Interpreter" → Select .venv |
|
||||
| pip version too old | Virtual environment defaults to old version | `pip install --upgrade pip` |
|
||||
| requirements.txt missing dependencies | Not exported | `pip freeze > requirements.txt` |
|
||||
|
||||
### One-click environment reset
|
||||
|
||||
Environment completely messed up? Delete and restart:
|
||||
|
||||
```bash
|
||||
# Delete old environment
|
||||
rm -rf .venv
|
||||
|
||||
# Recreate
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>📦 Node.js Environment Related</strong></summary>
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Node version mismatch | Project requires specific version | Use nvm to manage multiple versions: `nvm install 18` |
|
||||
| `npm install` error | Network/Permission issues | Change registry, clear cache, delete `node_modules` and reinstall |
|
||||
| Global package not found | PATH not configured | Add `npm config get prefix` to PATH |
|
||||
| package-lock conflict | Collaborative work | Use `npm ci` instead of `npm install` consistently |
|
||||
| `node_modules` too large | Normal phenomenon | Add to `.gitignore`, do not commit |
|
||||
|
||||
### Common Commands
|
||||
|
||||
```bash
|
||||
# Change to Taobao registry
|
||||
npm config set registry https://registry.npmmirror.com
|
||||
|
||||
# Clear cache
|
||||
npm cache clean --force
|
||||
|
||||
# Delete and reinstall
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
|
||||
# Use nvm to switch Node version
|
||||
nvm use 18
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🔧 Environment Configuration Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Command not found | Environment variables not configured | Check PATH, restart terminal |
|
||||
| Port occupied | Not properly shut down last time | `lsof -i :port_number` or `netstat -ano \| findstr :port_number` |
|
||||
| Insufficient permissions | Linux/Mac permissions | `chmod +x` or `sudo` |
|
||||
| Environment variables not taking effect | Not sourced | `source ~/.bashrc` or restart terminal |
|
||||
| .env file not taking effect | Not loaded | Use `python-dotenv` or `dotenv` package |
|
||||
| Windows path issues | Backslashes | Use `/` or `\\` or `Path` library |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🌐 Network Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| GitHub access slow/timeout | Network restrictions | Configure proxy, refer to [Network Environment Configuration](../从零开始vibecoding/01-网络环境配置.md) |
|
||||
| API call failed | Network/Key issue | Check proxy, API Key validity |
|
||||
| Terminal not using proxy | Incomplete proxy configuration | Set environment variables (see below) |
|
||||
| SSL certificate error | Proxy/Time issue | Check system time, or temporarily disable SSL verification |
|
||||
| pip/npm download slow | Source is abroad | Change to domestic mirror source |
|
||||
| git clone timeout | Network restrictions | Configure git proxy or use SSH |
|
||||
|
||||
### Terminal Proxy Configuration
|
||||
|
||||
```bash
|
||||
# Temporary setting (effective in current terminal)
|
||||
export http_proxy=http://127.0.0.1:7890
|
||||
export https_proxy=http://127.0.0.1:7890
|
||||
|
||||
# Permanent setting (add to ~/.bashrc or ~/.zshrc)
|
||||
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
|
||||
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Git Proxy
|
||||
git config --global http.proxy http://127.0.0.1:7890
|
||||
git config --global https.proxy http://127.0.0.1:7890
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>📝 Code Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Code file too large, AI cannot process | Exceeds context | Split files, only provide relevant parts to AI |
|
||||
| Code changes not taking effect | Cache/Not saved | Clear cache, confirm save, restart service |
|
||||
| Merge conflicts | Git conflicts | Let AI help resolve: paste conflict content |
|
||||
| Dependency version conflicts | Incompatible versions | Specify version numbers, or isolate with virtual environments |
|
||||
| Chinese garbled characters | Encoding issue | Consistently use UTF-8, add `# -*- coding: utf-8 -*-` at file beginning |
|
||||
| Hot update not taking effect | Watch issue | Check if file is within watch scope |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🎯 Claude Code / Cursor Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Claude Code cannot connect | Network/Authentication | Check proxy, re-run `claude login` |
|
||||
| Cursor completion is slow | Network latency | Check proxy configuration |
|
||||
| Quota exhausted | Limited free quota | Change account or upgrade to paid |
|
||||
| Rules file not taking effect | Path/Format error | Check `.cursorrules` or `CLAUDE.md` location |
|
||||
| AI cannot read project files | Workspace issue | Confirm opened in correct directory, check .gitignore |
|
||||
| Generated code in wrong location | Cursor position | Place cursor at correct position before generating |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🚀 Deployment Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Runs locally, fails on deployment | Environment differences | Check Node/Python versions, environment variables |
|
||||
| Build timeout | Project too large | Optimize dependencies, increase build time limit |
|
||||
| Environment variables not taking effect | Not configured | Set environment variables on the deployment platform |
|
||||
| CORS cross-origin error | Backend not configured | Add CORS middleware |
|
||||
| Static files 404 | Path issue | Check build output directory configuration |
|
||||
| Insufficient memory | Free tier limitations | Optimize code or upgrade plan |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🗄️ Database Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Connection refused | Service not started | Start database service |
|
||||
| Authentication failed | Incorrect password | Check username/password, reset password |
|
||||
| Table does not exist | Not migrated | Run migration |
|
||||
| Data loss | Not persistent | Docker add volume, or use cloud database |
|
||||
| Too many connections | Connections not closed | Use connection pool, close connections promptly |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🐳 Docker Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Image pull failed | Network issue | Configure image accelerator |
|
||||
| Container failed to start | Port conflict/Configuration error | Check logs `docker logs container_name` |
|
||||
| File changes not taking effect | Volume not mounted | Add `-v` parameter to mount directory |
|
||||
| Insufficient disk space | Too many images | `docker system prune` to clean up |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🧠 Large Model Usage Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Token limit exceeded | Input too long | Simplify context, only provide essential information |
|
||||
| Response truncated | Output token limit | Ask AI to output in segments, or say "continue" |
|
||||
| Large differences in model results | Different model characteristics | Select model based on task: Claude for code, GPT for general use |
|
||||
| Temperature parameter effect | Temperature setting | Use low temperature (0-0.3) for code generation, high for creativity |
|
||||
| System prompt ignored | Prompt too long/conflicting | Simplify system prompt, put important parts first |
|
||||
| JSON output format error | Model instability | Use JSON mode, or ask AI to only output code blocks |
|
||||
| Multi-turn conversation quality degrades | Context pollution | Periodically start new conversations, keep context clean |
|
||||
| API call error 429 | Rate limit | Add delay and retry, or upgrade API plan |
|
||||
| Streaming output garbled | Encoding/Parsing issue | Check SSE parsing, ensure UTF-8 |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🏗️ Software Architecture Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Code becomes messy with changes | No architectural design | Draw architecture diagram first, then write code |
|
||||
| Changing one place breaks many others | Tight coupling | Split modules, define clear interfaces |
|
||||
| Don't know where to put code | Confused directory structure | Refer to [General Project Architecture Template](../模板与资源/通用项目架构模板.md) |
|
||||
| Too much duplicate code | Lack of abstraction | Extract common functions/components |
|
||||
| State management chaotic | Global state abuse | Use state management library, unidirectional data flow |
|
||||
| Configuration scattered | No unified management | Centralize into config files or environment variables |
|
||||
| Difficult to test | Too many dependencies | Dependency injection, mock external services |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🔄 Git Version Control Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Committed unintended files | .gitignore not configured | Add to .gitignore, `git rm --cached` |
|
||||
| Committed sensitive information | Not checked | Use git-filter-branch to clean history, change key |
|
||||
| Cannot resolve merge conflicts | Unfamiliar with Git | Use VS Code conflict resolution tool, or ask AI for help |
|
||||
| Commit message written incorrectly | Accidental | `git commit --amend` to modify |
|
||||
| Want to undo last commit | Committed wrongly | `git reset --soft HEAD~1` |
|
||||
| Too many messy branches | No standardization | Use Git Flow or trunk-based |
|
||||
| Push rejected | New commits on remote | `pull --rebase` first, then push |
|
||||
|
||||
### Common Git Commands
|
||||
|
||||
```bash
|
||||
# Undo changes in working directory
|
||||
git checkout -- filename
|
||||
|
||||
# Undo changes in staging area
|
||||
git reset HEAD filename
|
||||
|
||||
# Undo last commit (keep changes)
|
||||
git reset --soft HEAD~1
|
||||
|
||||
# View commit history
|
||||
git log --oneline -10
|
||||
|
||||
# Stash current changes
|
||||
git stash
|
||||
git stash pop
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🧪 Testing Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Don't know what to test | Lack of testing mindset | Test edge cases, exceptions, core logic |
|
||||
| Tests are too slow | Test granularity too large | Write more unit tests, fewer E2E |
|
||||
| Tests are unstable | Depends on external services | Mock external dependencies |
|
||||
| Tests pass but bugs appear in production | Incomplete coverage | Add edge case tests, check with coverage |
|
||||
| Changing code requires changing tests | Tests coupled to implementation | Test behavior, not implementation |
|
||||
| AI generated tests are useless | Only tests happy path | Ask AI to supplement edge case and exception tests |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>⚡ Performance Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Page loads slowly | Resources too large | Compression, lazy loading, CDN |
|
||||
| API response slow | Queries not optimized | Add indexes, caching, pagination |
|
||||
| Memory leak | Resources not cleaned up | Check event listeners, timers, closures |
|
||||
| High CPU usage | Infinite loop/Redundant computation | Use profiler to locate hotspots |
|
||||
| Database queries slow | N+1 issue | Use JOIN or batch queries |
|
||||
| Frontend lagging | Too many re-renders | React.memo, useMemo, virtualized lists |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🔐 Security Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| API Key leaked | Committed to Git | Use environment variables, add to .gitignore |
|
||||
| SQL Injection | SQL concatenation | Use parameterized queries/ORM |
|
||||
| XSS Attack | User input not escaped | Escape HTML, use CSP |
|
||||
| CSRF Attack | No token verification | Add CSRF token |
|
||||
| Password stored in plaintext | Lack of security awareness | Use bcrypt or other hashing algorithms |
|
||||
| Sensitive information in logs | Printed unintended data | Anonymize, disable debug in production |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>📱 Frontend Development Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Styles not taking effect | Priority/Cache | Check selector priority, clear cache |
|
||||
| Mobile adaptation issues | Not responsive | Use rem/vw, media queries |
|
||||
| White screen | JS error | Check console, add error boundaries |
|
||||
| State not synchronized | Asynchronous issues | Use useEffect dependencies, or state management library |
|
||||
| Component not updating | Reference not changed | Return new object/array, do not modify directly |
|
||||
| Build size too large | Not optimized | On-demand import, code splitting, tree shaking |
|
||||
| Cross-origin issues | Browser security policy | Backend configure CORS, or use proxy |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🖥️ Backend Development Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| API returns slowly | Synchronous blocking | Use async, put time-consuming tasks in queue |
|
||||
| Concurrency issues | Race conditions | Add locks, use transactions, optimistic locking |
|
||||
| Service crashed undetected | No monitoring | Add health checks, alerts |
|
||||
| Logs cannot find issues | Incomplete logs | Add request_id, structured logging |
|
||||
| Configure different environments | Hardcoding | Use environment variables to distinguish dev/prod |
|
||||
| OOM crash | Memory leak/Too much data | Pagination, streaming, check for leaks |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🔌 API Design Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| API naming chaotic | No standardization | Follow RESTful, use HTTP verbs for actions |
|
||||
| Return format inconsistent | No agreement | Unify response structure `{code, data, message}` |
|
||||
| Version upgrade difficult | No version control | Add version number to URL `/api/v1/` |
|
||||
| Documentation and implementation inconsistent | Manual maintenance | Use Swagger/OpenAPI for auto-generation |
|
||||
| Error messages unclear | Only returns 500 | Refine error codes, return useful information |
|
||||
| Pagination parameters inconsistent | Each written differently | Unify `page/size` or `offset/limit` |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>📊 Data Processing Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Data format incorrect | Type conversion issues | Perform type validation and conversion |
|
||||
| Timezone issues | Timezones not unified | Store UTC, convert to local time for display |
|
||||
| Precision loss | Floating point issues | Use integers (cents) for monetary values, or Decimal |
|
||||
| Large file processing OOM | Loaded all at once | Stream processing, chunked reading |
|
||||
| Encoding issues | Not UTF-8 | Consistently use UTF-8, specify encoding when reading files |
|
||||
| Null value handling | null/undefined | Perform null checks, provide default values |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
<details open>
|
||||
<summary><strong>🤝 Collaboration Related</strong></summary>
|
||||
|
||||
| Issue | Reason | Solution |
|
||||
|:---|:---|:---|
|
||||
| Code style inconsistent | No standardization | Use ESLint/Prettier/Black, unify configuration |
|
||||
| PR too large, difficult to review | Too many changes | Commit in small steps, one PR per feature |
|
||||
| Documentation outdated | No one maintains | Update code and documentation together, CI checks |
|
||||
| Don't know who is responsible | No owner | Use CODEOWNERS file |
|
||||
| Reinventing the wheel | Unaware of existing solutions | Establish internal component library/documentation |
|
||||
|
||||
</details>
|
||||
|
||||
1. **Check error messages** - Copy the full error to AI
|
||||
2. **Minimum reproduction** - Find the simplest code that reproduces the issue
|
||||
3. **Bisection method** - Comment out half the code to narrow down the problem scope
|
||||
4. **Change environment** - Try different browsers/terminals/devices
|
||||
5. **Restart magic** - Restart service/editor/computer
|
||||
6. **Delete and restart** - If the environment is messed up, delete and recreate the virtual environment
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Ultimate Solution
|
||||
|
||||
Still can't figure it out? Try this prompt:
|
||||
|
||||
```
|
||||
I've encountered an issue and have tried many methods without success.
|
||||
|
||||
Error message:
|
||||
[Paste full error]
|
||||
|
||||
My environment:
|
||||
- Operating system:
|
||||
- Python/Node version:
|
||||
- Relevant dependency versions:
|
||||
|
||||
I have tried:
|
||||
1. xxx
|
||||
2. xxx
|
||||
|
||||
Please help me analyze the possible causes and provide solutions.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Contribution
|
||||
|
||||
Found a new pitfall? Welcome PR contributions!
|
||||
@@ -0,0 +1,520 @@
|
||||
# To understand 100% of the code, you must master the complete list of "language-level elements"
|
||||
|
||||
---
|
||||
|
||||
# I. First, correct a key misconception
|
||||
|
||||
❌ Misconception:
|
||||
|
||||
> Don't understand code = Don't understand syntax
|
||||
|
||||
✅ Truth:
|
||||
|
||||
> Don't understand code = **Don't understand a certain layer of its model**
|
||||
|
||||
---
|
||||
|
||||
# II. Understanding 100% of the code = Mastering 8 Levels
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L1: Basic Control Syntax (Lowest Threshold)
|
||||
|
||||
This layer you already know:
|
||||
|
||||
```text
|
||||
Variables
|
||||
if / else
|
||||
for / while
|
||||
Functions / return
|
||||
```
|
||||
|
||||
👉 Can only understand **tutorial code**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L2: Data and Memory Model (Very Critical)
|
||||
|
||||
You must understand:
|
||||
|
||||
```text
|
||||
Value vs Reference
|
||||
Stack vs Heap
|
||||
Copy vs Share
|
||||
Pointer / Reference
|
||||
Mutable / Immutable
|
||||
```
|
||||
|
||||
Example you need to "instantly understand":
|
||||
|
||||
```c
|
||||
int *p = &a;
|
||||
```
|
||||
|
||||
```python
|
||||
a = b
|
||||
```
|
||||
|
||||
👉 This is the **root cause of the differences in C / C++ / Rust / Python**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L3: Type System (Major Part)
|
||||
|
||||
You need to know:
|
||||
|
||||
```text
|
||||
Static Typing / Dynamic Typing
|
||||
Type Inference
|
||||
Generics / Templates
|
||||
Type Constraints
|
||||
Null / Option
|
||||
```
|
||||
|
||||
For example, you need to see at a glance:
|
||||
|
||||
```rust
|
||||
fn foo<T: Copy>(x: T) -> Option<T>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L4: Execution Model (Where 99% of Newcomers Get Stuck)
|
||||
|
||||
You must understand:
|
||||
|
||||
```text
|
||||
Synchronous vs Asynchronous
|
||||
Blocking vs Non-blocking
|
||||
Threads vs Coroutines
|
||||
Event Loop
|
||||
Memory Visibility
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
await fetch()
|
||||
```
|
||||
|
||||
You need to know **when it executes and who is waiting for whom**.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L5: Error Handling and Boundary Syntax
|
||||
|
||||
```text
|
||||
Exceptions vs Return Values
|
||||
panic / throw
|
||||
RAII
|
||||
defer / finally
|
||||
```
|
||||
|
||||
You need to know:
|
||||
|
||||
```go
|
||||
defer f()
|
||||
```
|
||||
|
||||
**When it executes, and if it's guaranteed to execute**.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L6: Meta-Syntax (Making Code "Look Less Like Code")
|
||||
|
||||
This is the root cause why many "don't understand":
|
||||
|
||||
```text
|
||||
Macros
|
||||
Decorators
|
||||
Annotations
|
||||
Reflection
|
||||
Code Generation
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
@cache
|
||||
def f(): ...
|
||||
```
|
||||
|
||||
👉 You need to know **what code it's rewriting**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L7: Language Paradigms (Determines Thinking)
|
||||
|
||||
```text
|
||||
Object-Oriented (OOP)
|
||||
Functional (FP)
|
||||
Procedural
|
||||
Declarative
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```haskell
|
||||
map (+1) xs
|
||||
```
|
||||
|
||||
You need to know this is **transforming a collection, not looping**.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L8: Domain Syntax & Ecosystem Conventions (The Last 1%)
|
||||
|
||||
```text
|
||||
SQL
|
||||
Regex
|
||||
Shell
|
||||
DSL (e.g., Pine Script)
|
||||
Framework Conventions
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```sql
|
||||
SELECT * FROM t WHERE id IN (...)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# III. The True "100% Understanding" Formula
|
||||
|
||||
```text
|
||||
100% Understanding Code =
|
||||
Syntax
|
||||
+ Type Model
|
||||
+ Memory Model
|
||||
+ Execution Model
|
||||
+ Language Paradigm
|
||||
+ Framework Conventions
|
||||
+ Domain Knowledge
|
||||
```
|
||||
|
||||
❗**Syntax accounts for less than 30%**
|
||||
|
||||
---
|
||||
|
||||
# IV. Where will you get stuck? (Realistic Assessment)
|
||||
|
||||
| Symptom of being stuck | Actual missing |
|
||||
|:---|:---|
|
||||
| "Can't understand this line of code" | L2 / L3 |
|
||||
| "Why is the result like this?" | L4 |
|
||||
| "Where did the function go?" | L6 |
|
||||
| "The style is completely different" | L7 |
|
||||
| "This isn't programming, is it?" | L8 |
|
||||
|
||||
---
|
||||
|
||||
# V. Your True Engineering-Level Goal
|
||||
|
||||
🎯 **Not "memorizing syntax"**
|
||||
🎯 But being able to:
|
||||
|
||||
> "I don't know this language, but I know what it's doing."
|
||||
|
||||
This is the **true meaning of 100%**.
|
||||
|
||||
---
|
||||
|
||||
# VI. Engineering Addendum: L9–L12 (From "Understanding" to "Architecture")
|
||||
|
||||
> 🔥 Upgrade "understanding" to being able to **predict**, **refactor**, and **migrate** code
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L9: Time Dimension Model (90% of people completely unaware)
|
||||
|
||||
You not only need to know **how** the code runs, but also:
|
||||
|
||||
```text
|
||||
「When」 it runs
|
||||
「How long」 it runs
|
||||
「If」 it runs repeatedly
|
||||
「If」 it runs with a delay
|
||||
```
|
||||
|
||||
### You must be able to judge at a glance:
|
||||
|
||||
```python
|
||||
@lru_cache
|
||||
def f(x): ...
|
||||
```
|
||||
|
||||
* Is **one calculation, multiple reuses**
|
||||
* Or **re-executes every time**
|
||||
|
||||
```js
|
||||
setTimeout(fn, 0)
|
||||
```
|
||||
|
||||
* ❌ Not executed immediately
|
||||
* ✅ Is **after the current call stack is cleared**
|
||||
|
||||
👉 This is the root cause of **performance / bugs / race conditions / repeated execution**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L10: Resource Model (CPU / IO / Memory / Network)
|
||||
|
||||
Many people think:
|
||||
|
||||
> "Code is just logic"
|
||||
|
||||
❌ Wrong
|
||||
**Code = Language for scheduling resources**
|
||||
|
||||
You must be able to distinguish:
|
||||
|
||||
```text
|
||||
CPU-bound
|
||||
IO-bound
|
||||
Memory-bound
|
||||
Network-blocking
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```python
|
||||
for x in data:
|
||||
process(x)
|
||||
```
|
||||
|
||||
What you should ask is not "is the syntax correct?", but:
|
||||
|
||||
* Where is `data`? (Memory / Disk / Network)
|
||||
* Is `process` computing or waiting?
|
||||
* Can it be parallelized?
|
||||
* Can it be batched?
|
||||
|
||||
👉 This is the **starting point for performance optimization, concurrency models, and system design**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L11: Implicit Contracts & Non-Syntax Rules (Engineering Truths)
|
||||
|
||||
This is what **99% of tutorials won't write**, but you'll encounter daily in real projects.
|
||||
|
||||
### You must identify these "non-code rules":
|
||||
|
||||
```text
|
||||
Whether the function is allowed to return None
|
||||
Whether panic is allowed
|
||||
Whether blocking is allowed
|
||||
Whether it's thread-safe
|
||||
Whether it's reentrant
|
||||
Whether it's re-callable
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```go
|
||||
http.HandleFunc("/", handler)
|
||||
```
|
||||
|
||||
Implicit contracts include:
|
||||
|
||||
* handler **must not block for too long**
|
||||
* handler **may be called concurrently**
|
||||
* handler **must not panic**
|
||||
|
||||
👉 This layer determines if you can **"make it run"** or **"deploy it"**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 L12: Code Intent Layer (Top-Tier Capability)
|
||||
|
||||
This is the **architect / language designer level**.
|
||||
|
||||
What you need to achieve is not:
|
||||
|
||||
> "What is this code doing?"
|
||||
|
||||
But:
|
||||
|
||||
> "**Why did the author write it this way?**"
|
||||
|
||||
You need to be able to identify:
|
||||
|
||||
```text
|
||||
Is it preventing bugs?
|
||||
Is it preventing misuse?
|
||||
Is it trading performance for readability?
|
||||
Is it leaving hooks for future extensions?
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```rust
|
||||
fn foo(x: Option<T>) -> Result<U, E>
|
||||
```
|
||||
|
||||
You need to read:
|
||||
|
||||
* The author is **forcing callers to consider failure paths**
|
||||
* The author is **rejecting implicit nulls**
|
||||
* The author is **compressing the error space**
|
||||
|
||||
👉 This is **code review / architecture design / API design capability**
|
||||
|
||||
---
|
||||
|
||||
# VII. Ultimate Complete Edition: Total Table of 12 "Language-Level Elements"
|
||||
|
||||
| Level | Name | Determines if you can… |
|
||||
|:---|:---|:---|
|
||||
| L1 | Control Syntax | Write runnable code |
|
||||
| L2 | Memory Model | Avoid implicit bugs |
|
||||
| L3 | Type System | Understand code without comments |
|
||||
| L4 | Execution Model | Avoid async / concurrency pitfalls |
|
||||
| L5 | Error Model | Avoid resource leaks / crashes |
|
||||
| L6 | Meta-Syntax | Understand "code that doesn't look like code" |
|
||||
| L7 | Paradigm | Understand different styles |
|
||||
| L8 | Domain & Ecosystem | Understand real projects |
|
||||
| L9 | Time Model | Control performance and timing |
|
||||
| L10 | Resource Model | Write high-performance systems |
|
||||
| L11 | Implicit Contract | Write production-ready code |
|
||||
| L12 | Design Intent | Become an architect |
|
||||
|
||||
---
|
||||
|
||||
# VIII. Counter-Intuitive but True Conclusion
|
||||
|
||||
> ❗**A true "language master"**
|
||||
>
|
||||
> Doesn't just memorize a lot of language syntax
|
||||
>
|
||||
> But:
|
||||
>
|
||||
> 👉 **For the same piece of code, they see 6 more layers of meaning than others**
|
||||
|
||||
---
|
||||
|
||||
# IX. Engineering-Level Self-Test (Very Accurate)
|
||||
|
||||
When you see an unfamiliar piece of code, ask yourself:
|
||||
|
||||
1. Do I know where its data is? (L2 / L10)
|
||||
2. Do I know when it executes? (L4 / L9)
|
||||
3. Do I know what happens if it fails? (L5 / L11)
|
||||
4. Do I know what the author is trying to prevent? (L12)
|
||||
|
||||
✅ **All YES = Truly 100% Understood**
|
||||
|
||||
---
|
||||
|
||||
# X. Recommended Learning Resources for Each Level
|
||||
|
||||
| Level | Recommended Resources |
|
||||
|:---|:---|
|
||||
| L1 Control Syntax | Official tutorials for any language |
|
||||
| L2 Memory Model | "Computer Systems: A Programmer's Perspective" (CSAPP) |
|
||||
| L3 Type System | "Types and Programming Languages" |
|
||||
| L4 Execution Model | "JavaScript Asynchronous Programming", Rust async book |
|
||||
| L5 Error Model | Go/Rust official error handling guides |
|
||||
| L6 Meta-Syntax | Python decorator source code, Rust macro mini-book |
|
||||
| L7 Paradigm | "Functional Programming Thinking", Haskell introduction |
|
||||
| L8 Domain Ecosystem | Framework official documentation + source code |
|
||||
| L9 Time Model | Practical performance analysis tools (perf, py-spy) |
|
||||
| L10 Resource Model | "Systems Performance: Enterprise and the Cloud" |
|
||||
| L11 Implicit Contract | Read CONTRIBUTING.md of well-known open-source projects |
|
||||
| L12 Design Intent | Participate in Code Review, read RFC/design documents |
|
||||
|
||||
---
|
||||
|
||||
# XI. Common Language Level Comparison Table
|
||||
|
||||
| Level | Python | Rust | Go | JavaScript |
|
||||
|:---|:---|:---|:---|:---|
|
||||
| L2 Memory | Reference-based, GC | Ownership + Borrowing | Value/Pointer, GC | Reference-based, GC |
|
||||
| L3 Type | Dynamic, type hints | Static, strong typing | Static, concise | Dynamic, TS optional |
|
||||
| L4 Execution | asyncio/GIL | tokio/async | goroutine/channel | event loop |
|
||||
| L5 Error | try/except | Result/Option | error return values | try/catch/Promise |
|
||||
| L6 Meta-Syntax | Decorators/metaclass | Macros | go generate | Proxy/Reflect |
|
||||
| L7 Paradigm | Multi-paradigm | Multi-paradigm, leaning FP | Procedural + Interfaces | Multi-paradigm |
|
||||
| L9 Time | GIL limits parallelism | Zero-cost async | Preemptive scheduling | Single-threaded event loop |
|
||||
| L10 Resource | CPU limited by GIL | Zero-cost abstractions | Lightweight goroutines | IO-bound friendly |
|
||||
|
||||
---
|
||||
|
||||
# XII. Practical Code Onion Peeling Example
|
||||
|
||||
Taking a FastAPI route as an example, layer-by-layer analysis:
|
||||
|
||||
```python
|
||||
@app.get("/users/{user_id}")
|
||||
async def get_user(user_id: int, db: Session = Depends(get_db)):
|
||||
user = await db.execute(select(User).where(User.id == user_id))
|
||||
if not user:
|
||||
raise HTTPException(status_code=404)
|
||||
return user
|
||||
```
|
||||
|
||||
| Level | What you should see |
|
||||
|:---|:---|
|
||||
| L1 | Function definition, if, return |
|
||||
| L2 | `user` is a reference, `db` is a shared connection |
|
||||
| L3 | `user_id: int` type constraint, automatic validation |
|
||||
| L4 | `async/await` non-blocking, does not occupy a thread |
|
||||
| L5 | `HTTPException` interrupts request, framework catches |
|
||||
| L6 | ` @app.get` decorator registers route, `Depends` dependency injection |
|
||||
| L7 | Declarative routing, functional processing |
|
||||
| L8 | FastAPI conventions, SQLAlchemy ORM |
|
||||
| L9 | Each request is an independent coroutine, `await` yields control |
|
||||
| L10 | IO-bound (database query), suitable for async |
|
||||
| L11 | `db` must be thread-safe, cannot share state across requests |
|
||||
| L12 | The author uses type hints + DI to enforce norms, preventing raw SQL and hardcoding |
|
||||
|
||||
---
|
||||
|
||||
# XIII. Training Path from L1→L12
|
||||
|
||||
## Phase One: Foundation Layer (L1-L3)
|
||||
- **Method** : LeetCode + Type gymnastics
|
||||
- **Goal** : Syntax proficiency, type intuition
|
||||
- **Practice** :
|
||||
- LeetCode 100 problems (any language)
|
||||
- TypeScript type gymnastics
|
||||
- Rust lifetime exercises
|
||||
|
||||
## Phase Two: Execution Layer (L4-L6)
|
||||
- **Method** : Read asynchronous framework source code
|
||||
- **Goal** : Understand runtime behavior
|
||||
- **Practice** :
|
||||
- Hand-write a simple Promise
|
||||
- Read asyncio source code
|
||||
- Write a Python decorator library
|
||||
|
||||
## Phase Three: Paradigm Layer (L7-L9)
|
||||
- **Method** : Rewrite the same project in multiple languages
|
||||
- **Goal** : Understand design tradeoffs
|
||||
- **Practice** :
|
||||
- Implement the same CLI tool using Python/Go/Rust
|
||||
- Compare the performance and code volume of the three implementations
|
||||
- Analyze the differences in time models across languages
|
||||
|
||||
## Phase Four: Architecture Layer (L10-L12)
|
||||
- **Method** : Participate in open-source Code Review
|
||||
- **Goal** : Understand design intent
|
||||
- **Practice** :
|
||||
- Submit PRs to well-known projects and receive reviews
|
||||
- Read RFC/design documents for 3 projects
|
||||
- Write an API design document and have others review it
|
||||
|
||||
---
|
||||
|
||||
# XIV. Ultimate Test: Which layer have you reached?
|
||||
|
||||
| Capability | Layer |
|
||||
|:---|:---|
|
||||
| Can write runnable code | L1-L3 |
|
||||
| Can debug async/concurrent bugs | L4-L6 |
|
||||
| Can quickly pick up new languages | L7-L8 |
|
||||
| Can perform performance optimization | L9-L10 |
|
||||
| Can write production-grade code | L11 |
|
||||
| Can design API/architecture | L12 |
|
||||
|
||||
> 🎯 **The goal is not "to learn all 12 layers", but "to know which layer you're stuck on when you encounter a problem"**
|
||||
@@ -11,3 +11,5 @@ Core concepts and methodology for Vibe Coding.
|
||||
- [The Way of Programming](./The%20Way%20of%20Programming.md)
|
||||
- [Code Organization](./Code%20Organization.md)
|
||||
- [General Project Architecture Template](./General%20Project%20Architecture%20Template.md)
|
||||
- [Common Pitfalls](./Common%20Pitfalls.md) - Common issues and solutions
|
||||
- [Language Layer Elements](./Language%20Layer%20Elements.md) - 12-level code understanding framework
|
||||
|
||||
Reference in New Issue
Block a user