代码规范
2022-5-8
| 2024-3-18
0  |  Read Time 0 min
type
status
date
slug
summary
tags
category
icon
password
1. 概述1.1. 代码规范原则1.2. 行业基础规范1.3. 开发流程原则2. Android 代码规范2.1. Git 仓库和项目命名规范2.2. 注释规范2.3. 代码文件规范2.4. 命名规范2.5. 项目规范3. 参考文档

1. 概述

好的代码规范不但有利于团队成员每个人都写出清晰、可读性高的代码，也便于成员之间沟通与互相学习

1.1. 代码规范原则

  • 把复杂得代码变简单，把简单的代码变优雅
  • 你想看到什么样的代码，你就写出什么样的代码

1.2. 行业基础规范

1.3. 开发流程原则

大部分时间我们都在写业务代码，但真正把业务代码写好并不是一件容易的事情，例如下面这些问题：
  1. 对自定义 View、事件分发、Handler 机制等 Android 基础知识点原理理解有多少（例如 action/actionMasked,GestureDetector/GestureDetectorCompat 分别选择那个更合适呢）
  1. 对标记为 deprecation 的函数和类是否都已进行对应处理
  1. 能否在原生基础上做最小的改动实现项目的交互需求（例如 RecyclerView、Adapter、LayoutManger 实现项目各种交互）
  1. 什么是死锁、什么是协程、什么是属性动画、什么是 RESTful、什么是控制反转、什么是面向切面编程等等，能否简单直白给出精确定义（这些很常见的概念，浏览别人博客当时都可以轻松理解，但只有自己写文档、遇到相关问题时独立思考才能有真正的理解）
  1. 对于像 mvvm 这样每个人都有不同理解的概念，能否结合公司项目特点给出自己的最佳实践
  1. 是否经常使用流程图、类图、时序图，能否有效表达自己的意图，把复杂的逻辑简单化
  1. 代码和注释是否符合行业规范，是否能不加修改发布或分享公示
这样的问题每天都会遇到，如果对所使用的框架不熟悉，套用代码即使代码正常运行但有可能埋下隐患，而杂乱无章的代码风格也会增加自己和别人阅读、维护的难度并因此消磨团队更多的时间和精力，最可怕的是致使团队陷入维护混乱代码的泥潭，使得每个人都得不到个人技术的提升。
我们欣赏深入浅出、严谨审慎的编码态度，越是细小的地方越能折射出一个人的代码素养，写业务代码也同样需要有足够的深度与广度，高质量代码始终是我们坚持的原则。
所以对于需求开发过程中遇到的技术难点，例如针对三方框架选型、项目公共组件编写、自定义 View 、复杂交互、一级页面性能要求等等，依据具体情况尽可能遵循以下流程：
  • 阅读相关技术文档与源代码，对深度、广度理解达到当前需求所要求的层次
  • 编写 demo 进行验证，并做压力测试，考虑时间复杂度、空间复杂度
  • 编写技术 RFC ，并通过团队成员评审
  • 编写代码并优化
遇到工期紧、或者前期技术准备需要较长时间周期的场景，在工期与代码质量之间做适当平衡，并对有风险、后续可以改进的代码进行标注。

2. Android 代码规范

2.1. Git 仓库和项目命名规范

  • Git 仓库命名推荐使用小写字母加 "-" 的形式
    • Android 工程命名推荐使用小写字母加 "-" 的形式
      • Android Module 命名推荐使用小写字母加 "-" 的形式，或者大写字母开头驼峰形式，但要保持整个工程统一

      2.2. 注释规范

      有一个简易的准则，写注释时，应该更倾向于表述相关代码的原因或目的，不妨站在读者的角度思考和提供注释：
      • 这是为了解决什么问题
      • 为什么做这个奇怪的改动
      • 为什么要用这么特别的做法
      • 为什么代码不得不这么写
      • 大片代码是否难以快速理解，如果是这样，我可否做一个简单说明在干什么
      • 使用非常规方式或者变通方式实现的内心不安的代码是否需要加以说明
      大部分时候，代码本身我们都能看懂，所有没必要通过自然语言复述，这样反而阻碍一目了然的阅读，浪费时间，影响心情。而代码背后的原因，往往更是令人关心，我们应该首要考虑针对此提供注释，不仅利于 code review 减少沟通和返工成本，而且其实也利于我们自己，因为代码就算是自己写的，一段时间再回来看它们时，如果没有注释或 commit message 说明原因，我们自己都很难想起为什么当初要那么做，不知道原因是很可怕的，因为这将导致我们不敢随随便便去对一些奇怪的代码做变更或增加回归测试的成本（这无边无际的重复工作让人沮丧，并且心有不安）
      注释规范：
      • "//"后面加一个空格
         
        • 汉字与英文字母数字之间加一个空格
           
          • TODO 后面添加":" 并添加空格
             
            • 类注释
               
              • 函数注释

                2.3. 代码文件规范

                • kt 、 java、xml 文件规范
                • 函数规范，函数内部代码不留空行，保持紧凑
                • 函数顺序规范
                函数嵌套时，函数顺序尽可能保持一致，或者参照遵循 Google 原生 api 里面的排序方式

                2.4. 命名规范

                遵循简洁性、表达性、一致性原则
                • 简洁性：使用统一规范的命名方式，添加通用前缀等
                • 表达性：命名使用英文单词准确表达类、函数、字段的作用，避免命名过长对英文单词做适当缩写，如果命名本身就有很好表达类、函数、字段的作用，可以省略不必要的注释
                • 一致性：对同样语义的内容所做的命名，在各个出现的地方都要保持一致
                例如：同样表示手机号，不能在一个文件里面命名为 phoneNumber ，另一个文件里面命名为 mobile，而在另一个出现的地方又命名为 phone
                例如：自定义 View 里面，对 AttributeSet 的解析的抽取函数，不能一个地方命名 initAttrs(attrs)，另一个地方命名为 resolveAttrs(attrs)，同一个人尽可能保持同一种输出
                主要命名事项：
                • 属性命名
                kt 文件里面属性命名统一使用小写字母开头，java 文件里面可以保持 mXxx 这种形式，但是不要一会儿有 m ，一会儿有下划线
                • xml 文件里面 id 命名
                • drawable 资源命名
                可以把以 .xml 格式文件统一放入 drawable 资源目录中，图片资源统一放入 mipmap 文件目录中
                • values 文件命名
                  • 自定义 View 所对应的属性文件，单独创建对应文件，需要有自己的命名空间（前缀）
                    • colors 文件
                      • strings
                      • layout 文件命名

                      2.5. 项目规范

                      1. 代码风格向原生代码靠拢，遵循『Java开发手册』与 『kotlin 语言规范』
                      1. 不要依赖 alpha 这种版本，尽量依赖稳定版
                      1. 代码文件都需要进行格式化，包括 xml
                      1. 每一个 commit 的提交信息都需要概括修改的内容，不宜出现简单的 update 来了事
                      以上种种规则或许有很多不恰当的地方，有待日后慢慢完善，写代码本身就是一个不断成才的过程，把代码写好即是我们的原则与底线，又是我们不断进步的根基，既然作为开发者不可避免，那就养成良好的习惯把写代码变成一件赏心悦目的事情吧

                      3. 参考文档

                      Relate Posts :
                      技术分享
                    • 规范
                      • RxJava 基本使用Gitflow 使用规范
                      • Utterance
                      Catalog