Version: v1.0 Updated: 2026-01
1. Comment Conventions
End-of-line comments are prohibited
- ❌ End-of-line comments are prohibited(such as
command # 注释） - ✅ Comments should occupy their own line, placed above the code
Scope of Application：
- Shell script files (.sh)
- bash code blocks in Markdown documents
- shell commands in Dockerfile and Makefile
# ❌ 错误：行尾注释
curl -X POST https://api.example.com/data # 发送请求
docker run -d nginx # 启动容器
cp -r src/ dist/ # 复制文件
# ✅ 正确：注释独占一行
# 发送请求
curl -X POST https://api.example.com/data
# 启动容器
docker run -d nginx
# 复制文件
cp -r src/ dist/
Reasons：
- Comments are easily carried along when copying and pasting, causing command errors
- Long command + comment = overly long line, poor readability
- Inside a heredoc block,
#is not a comment but content
2. File Writing Methods
Recommended method: tee command
# ✅ 推荐：简洁、无嵌套引号
sudo tee /etc/fail2ban/jail.d/docker-nginx.local > /dev/null << 'EOF'
[docker-nginx]
enabled = true
filter = docker-nginx
logpath = /var/log/nginx/access.log
maxretry = 5
EOF
Append content
# ✅ 追加到文件
sudo tee -a /etc/hosts > /dev/null << 'EOF'
192.168.1.100 myserver
EOF
# ✅ 单行追加
echo '192.168.1.100 myserver' | sudo tee -a /etc/hosts
Methods to avoid
# ❌ 避免：嵌套引号复杂，易出错
sudo bash -c 'cat > /etc/xxx << EOF
content
EOF'
# ❌ 避免：需要转义内容中的特殊字符
sudo sh -c "echo 'line1\nline2' > /etc/xxx"
Method Comparison
| Method | Advantages | Disadvantages | Recommended Scenarios |
|---|---|---|---|
sudo tee |
Concise, no nesting | Requires > /dev/null to suppress output |
Preferred |
sudo bash -c 'cat >' |
No need for tee | Complex nested quotes | Not recommended |
| Temporary file + mv | Can be verified first | Many steps | Complex configuration |
3. Heredoc Quoting Rules
Prohibit variable expansion (recommended default)
# ✅ 'EOF' 带引号：内容原样输出，不解析变量
sudo tee /etc/xxx > /dev/null << 'EOF'
$HOME 不会被展开
$(command) 不会被执行
EOF
Variable expansion required
# EOF 不带引号：变量会被展开
sudo tee /etc/xxx > /dev/null << EOF
当前用户: $USER
当前目录: $(pwd)
EOF
Selection Principles
| Scenario | Usage | Reason |
|---|---|---|
| Configuration file | << 'EOF' |
Avoid accidental expansion |
| Template generation | << EOF |
Variables need to be inserted |
| When uncertain | << 'EOF' |
Safer |
4. Permissions and Paths
Root privileges required
# ✅ 正确：tee 配合 sudo
echo 'content' | sudo tee /etc/xxx
# ❌ 错误：重定向在 sudo 之外，权限不足
sudo echo 'content' > /etc/xxx
Paths with spaces
# ✅ 正确：双引号包裹路径
sudo tee "/etc/my config/file.conf" > /dev/null << 'EOF'
content
EOF
5. Script Conventions
File header
#!/usr/bin/env bash
set -euo pipefail
# 脚本说明（一句话）
set Option Descriptions
| Option | Effect |
|---|---|
-e |
Exit when a command fails |
-u |
Report an error when using an undefined variable |
-o pipefail |
If any command in a pipeline fails, the whole pipeline fails |
Variable Usage
# ✅ 推荐：使用 ${} 包裹
echo "Hello, ${name}"
# ✅ 推荐：设置默认值
db_host="${DB_HOST:-localhost}"
# ❌ 避免：裸变量（易与后续字符混淆）
echo "Hello, $name_suffix"
6. Common Patterns
Check whether a command exists
if ! command -v docker &> /dev/null; then
echo "docker 未安装"
exit 1
fi
Check files/directories
# 文件存在
[[ -f /path/to/file ]] && echo "文件存在"
# 目录存在
[[ -d /path/to/dir ]] || mkdir -p /path/to/dir
Safe deletion
# ✅ 使用变量时防止误删
rm -rf "${dir:?}"/*
# ❌ 危险：变量为空时会删除根目录
rm -rf $dir/*
7. Code Blocks in Documentation
When writing bash commands in Markdown documents, also follow the above conventions:
## 安装配置
创建配置文件：
```bash
sudo tee /etc/myapp/config.yml > /dev/null << 'EOF'
server:
port: 8080
host: 0.0.0.0
EOF
```