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设计难度相对较大,请严格控制以上提到的和未提到的模块,你的代码才能合并到最终项目哦。还有一些笔者也没经历过,期待小伙伴们的分享。