Created on Sat Jan 22 18:04:53 2022; Last updated on 2024-09-03T15:53:41+08:00 @author: Richie Bao

好的书写代码的习惯，可以让代码易读、易于调试、维护、重构和拓展，及易于迁移和共享。因此，在书写代码时有必要遵循有益于提升代码质量的规则，当这些规则逐渐内化为一种习惯时，也能够有效的提升书写代码的效率。

2.2.1 基本规则

  • 命名

变量、函数或类的命名习惯上有两种形式，一种是驼峰形式（Camel-case），例如rotateAngle；另一种是下划线分隔形式（underscore-separated，Snake-case），例如rotate_angle。因为 Rhino 中 API 的变量命名以驼峰形式出现，因此 Python Script 中的代码书写尽量与之保持一致。

  1. 命名时，使用英文，并使名称能够反映出所定义变量的含义。例如startPoint，为定义的开始点；
  2. 同时，具有描述性的命名，有时虽然长，但是要好于不明所以的缩写形式，例如startPointCoordinate要优于spc，相对缩写而言，命名应是是可读的；
  3. 如果缩写形式为通用可辨识的名称，也可以使用，例如startPtCoordi，但注意不要使用摸棱两可的缩写形式；
  4. 尽量保持多个同一含义的对象为同一命名的前缀（后缀），例如startPointCoordinate和endPointCoordinate保持了一致；
  5. 当需要根据变量名就能够判断出变量数据的结构类型，而不用print()打印查看，则可以把类型作为后缀，例如startPointList或者startPointDict；
  6. 为了保持定义的函数或者类具有通用性，在迁移或者调用时，避免新环境（上下文）与定义对象命名含义上的冲突。变量的命名应该保持通用性，例如一个函数可以按规则缩放任何几何体，其输入参数中有height参数名，而不应该命名为boxHeight，因为这不适用于其它类型的几何对象；
  7. 函数的命名尽量用动词，例如def updateCoordi():pass。 同时，尽量保持类似函数命名的一致性，例如def updateLength():pass。
  • 注释

注释有两种形式，一种是单行注释，使用#开头；另一种是多行注释，使用''' comments '''，或者""" comments """。

养成注释代码的习惯，可以增加代码的易读性，也可以作为个人重读代码的提示，增加阅读的速度。

  1. 但注释时，如果代码自身（例如命名）就具有很好的易读性，就不需再增加注释，避免冗余；
  2. 不要注释显而易见的代码语句，例如rs.AddArc3Pt(start, end, point_on_arc)；
  3. 在函数内部，可以增加函数说明，及输入输出参数的说明；
  4. 对于 Python Script 组件，通常在其顶部，增加该组件的功能说明，和组件输入和输出项的说明和数据类型。
  • 函数

一个函数尽量只做一件事，不仅可以避免繁杂冗余，也方便调用。如果包含多个功能，但是所调用该函数的对象仅需要执行其中一项功能，这就造成了使用上的不便。此时可以考虑是否使用类来处理包含多个功能的问题。如果可能，尽量让函数简短、简单。当函数传入的参数较多（或数量不确定）时，可以配合使用*args位置参数或者**kwargs关键字参数。

2.2.2 代码风格

Python 代码风格指的是书写 Python 代码应该遵循的一组约定，以确保代码的可读性、一致性和可维护性。风格通常在同一模块和同一函数保持一致，同一项目保持一致，同风格指南或共识性规范尽量保持一致。Python 社区广泛遵循的代码风格指南是 PEP 8（Python Enhancement Proposal 8）①（PEP 8 — the Style Guide for Python Code②），其中一些关键的代码风格原则涉及有缩进、行宽、空行、空格、命名约定、注释、文档字符串、导入、避免过度复杂的表达式和一致性等；而 Google 开源项目风格指南③提供了在开源项目中编写清晰、一致和可维护代码的指导方针。但是，个人在代码书写过程中，注意力主要集中在问题的解决上，例如书写 x + y = 1公式时，会直接书写为x+y=1，为加快书写速度在符号之间没有多敲击空格键。因为类似不符合风格规范的点会有很多，因此已经有很多可以自动格式化代码风格的编辑器、转换工具或者基于解释器的插件，这大幅度提升了代码编辑的效率并使之尽量保持了某一种代码风格，例如 Visual Studio Code（VSC）的扩展插件 autopep8 等。

注释（Notes）：

① PEP 8（Python Enhancement Proposal 8），（https://peps.python.org/pep-0008/）。

② PEP 8 — the Style Guide for Python Code，（https://pep8.org/）。

③ Google 开源项目风格指南，（https://github.com/google/styleguide）。