拒绝沟通（“别问我，看代码”）

代码即文档的迷思

"别问我，看代码"这句话在开发团队里经常听到。表面上看，这是一种高效的工作方式——代码本身就是最准确的文档。但实际上，这种态度往往导致团队协作效率低下，新人上手困难，甚至引发维护灾难。前端项目尤其如此，因为现代前端生态复杂多变，业务逻辑与UI交互深度耦合。

一个典型场景：新同事接手React组件时，面对300行的useEffect和一堆未经注释的状态流转，完全摸不清数据从何而来、为何触发重渲染。此时如果原作者只是甩下一句"逻辑都在代码里"，无异于让新人独自穿越迷宫。

沉默代码的代价

不沟通的代码会产生隐性成本。比如这段Vue组件：

<template>
  <div>
    <button @click="handleClick">提交</button>
    <p v-if="status === 1">状态A</p>
    <p v-else-if="status === 2">状态B</p>
  </div>
</template>

<script>
export default {
  data() {
    return {
      status: 0
    }
  },
  methods: {
    handleClick() {
      this.status = this.calculateStatus()
    }
  }
}

问题显而易见：status的数字含义不明，calculateStatus的内部逻辑缺失。三个月后当产品需要修改状态流转时，开发者不得不像考古学家一样逆向工程。更糟的是，如果原始开发者已离职，这些魔法数字就变成了永远的谜。

注释的艺术

好的注释不是重复代码，而是解释"为什么"。对比以下两种注释方式：

// 不好的注释
function formatDate(date) {
  // 格式化日期
  return date.toISOString().split('T')[0]
}

// 好的注释
function formatDate(date) {
  // 使用ISO格式避免时区问题，前端展示只需要日期部分
  return date.toISOString().split('T')[0]
}

在复杂业务逻辑中，这样的注释价值连城：

// 使用防抖处理高频输入，300ms延迟是经过AB测试的平衡值
// 注意：不能使用lodash的debounce，因为需要保留React事件池
const handleSearch = useMemo(() => debounce((query) => {
  fetchResults(query)
}, 300), [])

类型系统作为文档

TypeScript的类型注解本身就是一种沟通方式。比较这两段代码：

// 模糊的类型
function getUser(id) {
  return api.fetch(id)
}

// 明确的类型
interface User {
  id: string
  name: string
  roles: Array<'admin' | 'editor' | 'viewer'>
}

function getUser(id: string): Promise<User> {
  return api.fetch<User>(id)
}

后者不仅说明了参数要求，还明确了返回数据结构，甚至预定义了角色枚举值。配合VSCode的智能提示，这种类型定义比外部文档更即时可用。

提交信息的叙事性

Git提交信息是另一种常被忽视的沟通渠道。对比以下提交记录：

git commit -m "修复bug"

与：

git commit -m "修复购物车价格计算错误
- 当优惠券与满减同时存在时，JS浮点精度导致合计错误
- 改用decimal.js进行货币计算
- 相关issue #1234"

后者不仅记录了修改内容，还保留了决策上下文，这对后续的代码审查和问题追溯至关重要。

组件驱动的文档

现代前端工具链提供了更好的沟通方式。比如用Storybook编写组件用例：

// Button.stories.js
export default {
  title: 'Components/Button',
  component: Button,
  args: {
    variant: 'primary'
  }
}

const Template = (args) => <Button {...args} />

export const Primary = Template.bind({})
Primary.args = {
  children: '主要按钮',
  onClick: () => console.log('点击事件')
}

export const Disabled = Template.bind({})
Disabled.args = {
  children: '禁用状态',
  disabled: true
}

这种可视化文档比口头描述"按钮组件支持disabled属性"直观得多，也便于非技术人员验证UI表现。

错误信息的友好性

连错误处理都可以成为沟通渠道。比较这两个错误提示：

// 不友好的错误
throw new Error('Invalid state')

// 友好的错误
throw new Error(
  `表单校验失败: 
  - 邮箱格式不正确(当前值: ${email})
  - 密码需要包含大小写字母(当前强度: ${strength})
  参考文档: /docs/form-validation`
)

后者不仅指出问题所在，还提供具体错误值和解决方案线索，大大减少了排查时间。

文档即测试

JSDoc结合类型检查可以自动生成文档的同时验证代码正确性：

/**
 * 计算两个坐标点之间的距离
 * @param {{x: number, y: number}} point1 第一个点
 * @param {{x: number, y: number}} point2 第二个点
 * @returns {number} 两点距离，保留两位小数
 * @example
 * distance({x: 0, y: 0}, {x: 3, y: 4}) // => 5
 */
function distance(point1, point2) {
  const dx = point1.x - point2.x
  const dy = point1.y - point2.y
  return Math.sqrt(dx * dx + dy * dy).toFixed(2)
}

这种文档可以直接被IDE识别，在调用时显示参数提示，同时示例代码实际上构成了单元测试。

命名即沟通

变量命名是最基础的沟通形式。看这个状态管理例子：

// 模糊的命名
const [state, setState] = useState({
  a: [],
  b: false,
  c: null
})

// 清晰的命名
const [userPrefs, setUserPrefs] = useState({
  favoriteTopics: [],
  isSubscribed: false,
  lastVisited: null
})

后者不需要额外注释就能传达数据结构意图。在Redux的action命名中，这种沟通更重要：

// 意义模糊的action
dispatch({ type: 'UPDATE', payload: data })

// 自描述的action
dispatch({
  type: 'USER_PROFILE_LOAD_SUCCESS',
  payload: {
    userData: response.data,
    receivedAt: Date.now()
  }
})

代码审查作为教学时刻

拒绝沟通的团队常把代码审查变成形式主义。有效的审查应该像这样：

1. **components/Modal.js** 
   - 第45行的z-index值1024可能会与导航栏冲突(当前导航栏是1030)
   - 考虑提取`const MODAL_Z_INDEX = { base: 1000, top: 1100 }`

2. **hooks/useFetch.js**
   - 重试逻辑缺少最大重试次数限制，可能导致无限循环
   - 建议添加`maxRetries`参数，默认3次

这种审查既指出问题，也提供改进方案，成为团队知识传承的契机。

架构决策记录

重大技术决策应该用ADR(Architecture Decision Records)文档化：

# 采用CSS-in-JS方案

## 状态
2023-05-20 已通过

## 背景
现有CSS类名冲突率每月增长15%，BEM规范执行不一致

## 决策
选用Emotion作为CSS-in-JS解决方案，原因：
- 支持SSR关键CSS提取
- 类型安全的样式props
- 较小的运行时体积(7KB)

## 后果
- 需要培训团队成员
- 现有SCSS需要逐步迁移

这样的记录避免了日后无休止的"为什么不用Tailwind"的讨论。

沟通的自动化

甚至可以用工具强制沟通。比如ESLint规则：

// .eslintrc.js
module.exports = {
  rules: {
    'no-magic-numbers': ['error', { 
      ignore: [-1, 0, 1], // 允许基本数学数字
      ignoreArrayIndexes: true
    }],
    'jsdoc/require-jsdoc': ['warn', {
      require: {
        FunctionDeclaration: true,
        MethodDefinition: true
      }
    }]
  }
}

这些规则会"强迫"开发者用常量替代魔法数字，为函数添加文档注释，从制度上保证基本沟通质量。