FishBot项目编码规范V1.0.0.220621

小鱼

FishBot项目编码规范V1.0.0.220621

FishBot代码目前由C++、Python、C三种语言构成。本文主要针对三种语言编码规范、注释规范及单元测试工具进行介绍。

代码格式规范

针对C++、Python代码，参考Google编程规范。https://zh-google-styleguide.readthedocs.io/en/latest/。

针对C语言，主要用于EPS32开发，采用ESP32规范，https://docs.espressif.com/projects/esp-idf/zh_CN/v4.2.3/esp32/contribute/documenting-code.html

我们仅对代码格式及注释做出要求，对代码风格不做过多要求，但需要保证同一模块代码规范一致。

注释规范

好的注释有利于其他小伙伴学习我们的代码，并帮助做出改进，所以好的注释和注释规范对我们来说和规范一样重要。

函数注释：

C/C++:

使用vscode插件可以快速生成：Generate Doxygen Comments

函数注释

/**
 * @brief Set the Tunings object
 * 
 * @param Kp 
 * @param Ki 
 * @param Kd 
 * @param POn 
 */
void SetTunings(double Kp, double Ki, double Kd, int POn)
{
   if (Kp<0 || Ki<0 || Kd<0) return;

   pOn = POn;
   pOnE = POn == P_ON_E;

   dispKp = Kp; dispKi = Ki; dispKd = Kd;

   double SampleTimeInSec = ((double)SampleTime)/1000;
   kp = Kp;
   ki = Ki * SampleTimeInSec;
   kd = Kd / SampleTimeInSec;

  if(controllerDirection ==REVERSE)
   {
      kp = (0 - kp);
      ki = (0 - ki);
      kd = (0 - kd);
   }

文件头：

/**
 * @brief 启动入口文件
 * @author 小鱼 (fishros@foxmail.com)
 * @version V1.0.0
 * @date 2022-06-21
 * @copyright 版权所有：FishBot Open Source Organization
 */

Python 使用插件生成：Python Docstring Generator

函数注释
···

def pid(p:float,i:float,d:float):
"""summary

Args:
    p (float): _description_
    i (float): _description_
    d (float): _description_
"""
pass

···

文件头

'''
 @brief 简介
 @author your name (you@domain.com)
 @version V1.0.0
 @date 2022-06-21
 @copyright 版权所有：FishBot Open Source Organization
'''

单元测试工具

考虑到国内开发者习惯，单元测试不做强制要求，但需要统一单元测试工具。

C++使用GTEST
Python使用Pytest
嵌入式C使用Unity（ESP推荐）

具体单元测试规范根据后续开发情况更新。

上述内容仅小鱼快速制定，如有不合理之处欢迎回帖讨论。

小鱼

代码格式化方法及工具

C++使用clang-format进行格式化，使用cpplint做代码检查

sudo apt install clang-format-14
sudo pip install cpplint

Python使用pylint进行代码的检查，格式化则采用vscode默认的即可。