5. 阿里巴巴程序员开发手册黄山版( 三 ) _注释

所有的枚举类型字段必须要有注释，说明每个数据项的用途。与其用半吊子英文来注释，不如用中文注释说清楚。专有名词与关键字保持英文原文即可。代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等。在类中删除未使用的任何字段和方法、内部类；在方法中删除未使用的参数声明与内部变量。谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的另一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释又是相当大的负担。特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。
前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。前后端数据列表相关的接口返回，如果为空，则返回空数组[]或空集合{} 。服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，、、用户提示信息四个部分。前后端交互的 JSON 格式数据中，所有的 key 必须为小写字母开始的风格，符合英文表达习惯，且表意完整。是前后端错误追踪机制的体现，可以在前端输出到 type=“” 文字类控件中，或者用户端的日志中，帮助我们快速地定位出问题。
对于需要使用超大整数的场景，服务端一律使用字符串类型返回，禁止使用 Long 类型。Java 服务端如果直接返回 Long 整型数据给前端，会自动转换为类型（HTTP 请求通过 URL 传递参数时，不能超过 2048 字节。HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出错。

文章插图
在翻页场景中，用户输入参数的小于 1，则前端返回第一页参数给后端；后端发现用户输入的参数大于总页数，直接返回最后一页。服务器内部重定向必须使用；外部重定向地址必须使用 URL 统一代理模块生成，否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”，并且还会带来 URL 维护不一致的问题。
在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。枚举 enum（括号内）的属性字段必须是私有且不可变。任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。及时清理不再使用的代码段或配置信息。
好的单元测试必须遵守 AIR 原则，单元测试在线上运行时，感觉像空气（AIR）一样感觉不到，但在测试质量的保障上，却是非常关键的。好的单元测试宏观上来说，具有自动化、独立性、可重复执行的特点。
A：（自动化）
I：（独立性）
R：（可重复）
单元测试应该是全自动执行的，并且非交互式的。输出结果需要人工检查的测试不是一个好的单元测试。不准使用 .out 来进行人肉验证，单元测试必须使用来验证。保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。单元测试是可以重复执行的，不能受到外界环境的影响。核心业务、核心应用、核心模块的增量代码确保单元测试通过。