写在DeePMD-kit v2.0.0发布之际
时至2021年8月,从大三算起,我从事科研工作也快满四年了。四年来,我也用过不少计算软件,它们无一例外都有一些通病,一是文档写得极差,遇到不属于bug的错误总要手动搜索答案,形成了“软件使用经验”的壁垒,有些软件甚至催生了不少第三方论坛、博客、培训机构提供教程,形成了完整的产业链;二是对于开源项目来说,注释和开发文档几乎没有,看代码只能靠猜,给二次开发带来了极大障碍。
原先,DeePMD-kit也存在着这样的问题。当年我还是DeePMD-kit的用户时,就常常为了理解代码背后的逻辑而被折磨得痛不欲生。虽然解决这个问题需要付出的努力很多,但不积跬步,无以至千里;不积小流,无以成江海。这一问题仍需要去推动、去解决。v2.0.0对这个问题进行了针对性优化,虽然仍有很多欠缺之处,但是用林峰的一句话来说,算是“小学毕业”了。
新版的文档分为了三个板块,一是Getting started,通过一个简单的案例,供初学者入门;二是Advanced,为使用者带来了详细的文档和具体的参数;三是Developer Guide,包含了具体的Python和C++的API,供开发者参考。
API部分旨在为各个函数和类的功能和参数提供完整的注释,以DescrptSeA为例,DescrptSeA的公式和参数都放到了docstring内,相信能给二次开发带来极大的方便。有所欠缺的是,这个坑极大,目前有很多仍未完成。
C++的注释以InputNlist为例,没有注释的话没有人知道如何理解各个member。
另一方面,我在解答问题的时候能够发现,很多人都会遇到同样的不是bug的报错,而这些具体指南是可以写在error message里面的。v2.0.0增加了很多指南型的error message,用户遇到error后可以不去任何地方问,直接跟着指南走就行了。
总之,文档和注释目前仍然是一个很大的坑,但如果想让DeePMD-kit成为一个成熟的、经久不衰的开源软件,这就是一道必须面对的槛!