image.png
开源摘星计划（WeOpen Star） 是由腾源会 2022 年推出的全新项目，旨在为开源人提供成长激励，为开源项目提供成长支持，助力开发者更好地了解开源，更快地跨越鸿沟，参与到开源的具体贡献与实践中。

不管你是开源萌新，还是希望更深度参与开源贡献的老兵，跟随“开源摘星计划”开启你的开源之旅，从一篇学习笔记、到一段代码的提交，不断挖掘自己的潜能，最终成长为开源社区的“闪亮之星”。

我们将同你一起，探索更多的可能性！

项目地址：https://github.com/weopenprojects/WeOpen-Star

本文目标

在这次的OpenMLDB开源项目中，关于builtin函数的实现难度高、要求深。本人3个issue对应的pr提交了近60次才通过。为此记录以下规则，同时也是希望未来的开发者不再入坑。

CPP规范

cpp必须符合严格的规范，具体的有以下要求：

  • 每一行的行末不允许出现多余的空格（1个也不行）
  • 不要在"::","->","."前后加空格，不要在"，","；"之前加空格。
  • 在结尾的“；”后没有空格
  • 定义指针和引用时*和&紧跟变量名。
  • if语句写法举例：检测空指针
    • 正确写法：if (pointer)
    • 错误写法：if(pointer)、if( pointer)、if( pointer )、if(pointer) (仔细看，这里有一个空格)、if ( pointer )
  • 同理，检测非空指针，用 if (!p)。注意操作符严格在变量前。
  • 运算符：c = a + b。错误：c=a+b, c = a+b, c=a + b, c=a+ b
  • 循环语句同理

    关于函数

  • 函数参数比较多时，应考虑用struct代替，参数不能超过6个。
  • 如果不能避免函数参数比较多，应在排版上可考虑相似含义的参数占用一行，参数名竖向对齐。甚至每个参数一行。

    关于String与Date

    基本规则参考官方文档中StringRef, Timestamp*或 Date*的定义，不住赘述。特别的，笔者常用的StringRef在提交时有以下限制：

  • 不允许使用std::string在只有一行的时候，具体的可以用const char *代替。
  • ToString()方法用于提取StringRef里的string，返回值是std::string。
  • StringRef有且仅有两个变量：uint32t size; const char* data_;前者控制大小，后者控制数据。因此，如果创建StringRef，必须显式赋值这两个属性。

  • 如果返回值是StringRef，严格遵循以下四行代码，多或少均不通过。

    char *buffer = AllocManagedStringBuf(4);
output->size_ = 4;
memcpy(buffer, "true", output->size_);
output->data_ = buffer;

    测试、注册、文档

    尽管SQL函数注册名一般统一使用snake_case风格，但是测试用例是camelCase风格。请务必注意。
    同样的，注册的doc字符串也要遵循不在行尾多任何空格的要求，并且缩进也要符合要求，如下：

    RegisterExternal("function_name")
//...
.doc(R"(
        @brief a brief summary of the my_function's purpose and behavior（注意缩进和行尾）
（这里有空行）
                @param param1 a brief description of param1

      Example:
（这里也有一行）
      @code{.sql}（没有多的空格，注意这一行除了最开始，一个空格都没有）
         select my_function(1);
          -- output xxx（注意缩进）
      @endcode
      @since 0.4.0)");

    本文小结

    总的来说，builtin设计难度相对较大，请严格控制以上提到的和未提到的模块，你的代码才能合并到最终项目哦。还有一些笔者也没经历过，期待小伙伴们的分享。