| New file |
| | |
|---|
| | | # 前端工作共识 |
|---|
| | | |
|---|
| | | 尽管我们来自五湖四海，有着各自不同的编码习惯，但现在我们聚集在一起组成了一个团队。为了使团队合作更加流畅，减少沟通成本和内耗，我们需要在以下几个方面达成共识。 |
|---|
| | | |
|---|
| | | ## 1 代码首先是给人读的，其次才是给机器运行 |
|---|
| | | |
|---|
| | | 团队开发与个人开发最大的区别在于：你身处一个团队中，大家需要相互配合。因此，**让代码容易阅读是你应尽的责任**。 |
|---|
| | | |
|---|
| | | ### 1.1 代码命名必须有实体意义 |
|---|
| | | |
|---|
| | | > 好的代码，就像阅读小说一样流畅自然，看到哪里就能理解到哪里，是一种愉悦的体验，而不是像侦探破案一样需要推理猜测。 |
|---|
| | | |
|---|
| | | 要实现良好的阅读体验，代码命名必须包含与业务相关的真实实体名词： |
|---|
| | | |
|---|
| | | | 改前 | 改后 | 意义 | 实体词 | |
|---|
| | | | :--------------- | :--------------------- | :----------------- | :-------- | |
|---|
| | | | onValueChange | **onNoteValueChange** | 备注的值改变 | note | |
|---|
| | | | onSelectChange | **onFillSelectChange** | 充装记录的选择变化 | fill | |
|---|
| | | | onSelectedChange | **onSpecSelectChange** | 充装规格的选择变化 | spec | |
|---|
| | | | onItemChange | **onPriceTypeChange** | 价格类型变化 | priceType | |
|---|
| | | |
|---|
| | | 这样的命名方式带来两个显著好处： |
|---|
| | | 1. 做无关模块开发时可以快速跳过不相关代码 |
|---|
| | | 2. 做相关模块开发时一眼就能确定要查看的代码 |
|---|
| | | |
|---|
| | | 同时，让实体名词承担功能表述的作用，能让代码维护更依赖阅读而不是记忆，极大减轻记忆负担。 |
|---|
| | | |
|---|
| | | ### 1.2 设计良好的模块与分层结构 |
|---|
| | | |
|---|
| | | 优秀的代码结构应该是有序且层次分明的，而非杂乱无章的流水账。良好的模块与分层设计能帮助我们更高效地掌控和阅读代码： |
|---|
| | | |
|---|
| | | #### 1.2.1 显示与业务分离 |
|---|
| | | 将显示层与业务层清晰分开，各司其职： |
|---|
| | | - 显示层：专注于信息呈现和用户交互 |
|---|
| | | - 业务层：专注于数据处理和业务逻辑 |
|---|
| | | |
|---|
| | | 这种分离使我们能快速定位问题所在——是界面问题还是数据问题，一目了然 |
|---|
| | | |
|---|
| | | #### 1.2.2 主流程与次要操作分层 |
|---|
| | | 对于复杂的操作流程，我们应将各个操作步骤封装为独立组件： |
|---|
| | | - 主流程代码：保持简洁明了，仅包含关键流程和组件引用 |
|---|
| | | - 子组件：承担具体操作细节，各自负责单一职责 |
|---|
| | | |
|---|
| | | 这样设计后，主流程代码变得清晰易读，概览全局更加轻松。而当需要关注某个具体步骤时，只需查看相应的子组件即可，无需关注其他部分，大大提高了代码的掌控效率 |
|---|
| | | |
|---|
| | | #### 1.2.3 公共代码复用 |
|---|
| | | 模块化设计使代码复用变得自然而简单： |
|---|
| | | - 通用功能抽离为独立公共组件 |
|---|
| | | - 跨页面的相似逻辑统一封装子组件 |
|---|
| | | - 跨项目公共资源共享，减轻决策负担 |
|---|
| | | |
|---|
| | | 这不仅减少了代码冗余，还提高了开发效率和代码质量 |
|---|
| | | |
|---|
| | | ## 2 思考先行，开发随后 |
|---|
| | | |
|---|
| | | ### 2.1 理解清楚需求再动手 |
|---|
| | | |
|---|
| | | 由于我们的需求文档通常由老板和总监编写，没有专职人员完善需求细节，因此某些需求描述可能比较模糊 |
|---|
| | | 这种情况下，如果对业务理解不深，很容易导致开发的功能与实际需求不一致，最终需要重做 |
|---|
| | | |
|---|
| | | 因此，我们需要在开发过程中不断积累对业务的理解，至少要达到能发现需求歧义的程度 |
|---|
| | | |
|---|
| | | 有歧义是正常的——老板和总监对业务太熟悉了，往往会自然而然地认为某些理解是理所当然的； |
|---|
| | | 而对业务不熟悉的人，从需求文字字面出发，确实可能产生不同理解 |
|---|
| | | |
|---|
| | | 发现歧义时，请及时咨询我或旭诚，问清楚具体要求，一定要完全理解需求后再开始开发 |
|---|
| | | |
|---|
| | | ### 2.2 设计清晰方案再动手 |
|---|
| | | |
|---|
| | | 除了业务需求，在开发前我还应该梳理清楚技术形式、模块拆分和实现方式，以最简洁的方案实现需求，切忌盲目开工，为求速度而书写毫无章法的代码 |
|---|
| | | |
|---|
| | | 如果不重视工程质量，因为前端代码过于灵活，一段时间后代码混乱到无法维护了，就被迫需要重构，我们应该避免这样的事情发生 |
|---|
| | | |
|---|
| | | 只关注结果产量而不重视工程质量，这种代码是会被要求返工重写的 |
|---|
| | | |
|---|
| | | ## 3 用户体验是工作的一部分 |
|---|
| | | |
|---|
| | | 用户体验是我们前端开发者需要主动思考的问题，这是我们工作的重要组成部分 |
|---|
| | | |
|---|
| | | 我们公司的用户体验价值观是：**宁可技术实现复杂一些，也要让用户操作尽可能简单** |
|---|
| | | |
|---|
| | | 这不仅仅是口号，我们有着深入的实践经验： |
|---|
| | | |
|---|
| | | ### 3.1 前端技术密集型案例 |
|---|
| | | |
|---|
| | | 我们电子秤开票界面，有个支持全键盘操作表格，有众多客户反馈，我们经过讨论确认后，专门开发的用户体验改进功能 |
|---|
| | | |
|---|
| | | 这个表格看似简单，用起来也简单，这正是我们的目标 |
|---|
| | | |
|---|
| | | 但在技术层面，它是表格和表单的复合体，支持表格回车自动加行、方向键自由切换不同组件的焦点，以及表单验证等，集众多复杂功能于一体 |
|---|
| | | |
|---|
| | | ### 3.2 业务复杂型案例 |
|---|
| | | |
|---|
| | | 建档 app 中的"气瓶制造单位"选项 |
|---|
| | | 用户看到的只是一个普通下拉选框，旁边有个【管理】按钮可以增减选项内容，功能表面上看是很简单的 |
|---|
| | | |
|---|
| | | 但实际上，选项内容的变更需在同公司多个手机间同步，且这些厂家名称没有数据 ID，只能通过文字精确匹配 |
|---|
| | | 同时，输入名称必须符合工商注册名称，不能使用口语化的俗称，否则档案上传监管平台会通不过 |
|---|
| | | 还有，允许客户删除他们不需要的选项，仅从需要的厂家中选（对于新客户，支持一键恢复全国所有厂家，然后再慢慢删） |
|---|
| | | |
|---|
| | | 这种复杂性对用户是完全透明的 |
|---|
| | | |
|---|
