设计库时应遵循哪些准则?


11

我正在使用Uno进行Arduino项目。该项目包含大量代码。我想创建一个库,以后甚至可以共享它。设计库时应遵循哪些准则?


这不是更多的一般性问题,也许对于Stack Overflow来说-似乎其中的Arduino部分无关紧要。也就是说,它可能会为Arduino的内存约束提供有用的提示。

Answers:


12

设计库时,应牢记许多要点。您最终可能会与他人共享您的工作,因此遵循一致的设计模式非常重要。请记住,其他用户的技能水平将大相径庭,因此请尽可能设计一个易于使用的库。

基本技巧

销图

提供您的库期望的基本引脚图。不要使引脚映射保持静态,而是允许用户轻松进行更改。

工作图书馆

您应该尝试确保的第一件事是您的库正在运行。如果不是,请明确指出。您不想最终浪费时间尝试使用损坏的软件,因此也不要让其他人也这样做。

基本自述文件

非常清楚地提到库是为哪个板设计的,在哪个板上进行了测试,以及预期在哪个板上工作。指定此处提到的每个板的生成(版本)。

介面

接下来的事情是您应该具有明确定义的接口。具有复杂接口的工作库令人沮丧。这将帮助您自己以后使用该库,并使其他用户更轻松。这应该是要记住的最重要方面之一。

无论您采用自上而下还是自下而上的方法,界面都应该始终清晰明了。在自下而上的方法中,这可能并且将很困难,但是不应忽略它。否则,您将得到一个过于复杂的库,该库可能无法使用。

特殊功能

如果您有使用某些特殊电路板特性的功能,请确保使这些功能脱颖而出,请在自述文件和注释中进行提及。

繁忙的等待

在某些情况下,您可能必须使用繁忙的等待时间。根据程序逻辑,此类功能可能会阻止正常的控制流程,从而在执行关键任务时造成麻烦。如果可能,请尝试使用中断或其他算法。如果不是,则明确提及标记任何此类功能。

评论

确保对您所做的每一个小变化和大变化都保持评论。为所有关键功能写好长的注释,为其他关键功能写小注释。明确描述您的接口,每个参数,其作用以及返回的结果。这是很多额外的工作,但对您和其他人都将大有帮助。如果您有某些功能可能无法在不同的板上使用,请在此处进行说明。如果这些是其他功能正在使用的中间功能,并且可能有必要,请在自述文件中进行说明。

一致性

确保.h.cpp文件中的所有内容(包括注释)都一致。

仅将相关功能保留在一个文件中。拥有几个小但逻辑上一致的模块要比其中包含所有内容的一个大文件好。


进阶技巧

详细的自述文件

编写一个清晰的自述文件,描述该库,其功能,任何问题或错误以及基本可用性。如上所述,使用单独的文件定义和解释每个接口。

目录结构

一旦库变大,可能需要将其划分为目录。使用时,这不容易实现。但是,如果您到此为止,您可能是Arduino的高级用户,并且使用了更强大的开发工具。如果没有,这就是宇宙告诉你这样做。

发牌

确保添加许可证。

版本控制

使用VCS工具,例如Git或SVN。这将使查看更改,还原到旧版本,发现导致错误的代码,甚至与他人协作变得更加容易。


什么是图钉地图?
克里斯·安德森

2

AshRj的回答非常好-我要补充2点。

第一点:文档

AshRj建议编写详细的自述文件。尽管这可能是一个好习惯,但是它可以很快与较大的库失去联系-实际上,即使只有几千行(实际上并不多),自述文件也几乎没有好处。我的建议是更进一步,并使用等效的Javadoc for C ++-正如这个答案所解释的(在Stack Overflow上),Doxygen是一个非常有用的工具,可用于保持文档的可管理性和可操作性(没有人愿意编辑10K行自述文件...)

第二点:目录

再次与AshRj的答案形成对比,始终使用目录。即使您只有10个文件,甚至可能只有7个或8个文件,我都知道这听起来有些愚蠢,但这是对您的工作进行过时的证明,如果您不及早开始,您将最终陷入困境。文件。目录不仅仅适用于大型项目,小型目录也应使用它们。只需记住,在C ++(事实上的Arduino语言)中,包括库中的文件时,目录将被忽略-它们仅作为代码管理工具存在。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.