Documentation in a place and form that can easily be found and read, including
instructions on how to build it;
instructions on how to use it.
Some sort of confidence testing ("I compiled it, but does it work?").
Whether the docs are HTML, plain text or in-source comments; whether there's a Makefile or a batch script or a copy & paste one-liner in the README.txt; whether you've got a full-blown unit testsuite or a "golden file" test:
It doesn't matter really.
The important thing is that you can build it, test it, and use it as easily as possible.
Adding personal opinion:
KISS. (Keep it short and simple.)
Go with simple source comments for small projects, and only start the Doxygen stuff when you grow beyond a certain point. Make sure your documentation framework doesn't make it harder to find things via full-text search, because in my experience, that's what people end up doing unless you wrote your docs really well.
Go with a simple Makefile and use more sophisticated stuff (like CMake, automake etc.) only when it becomes necessary. For small projects, the amount of "metadata" in comparison to "real" source files can become ridiculous.
You can sink quite some time and energy in this "supporting cast", which - in the beginning of a project - should be put into the project itself. Build system, documentation etc. can grow as necessary, but the project architecture itself is a bitch to refactor once it's been released. That's where your primary focus should be.
发布评论
评论(1)
简化列表:
文档是 HTML、纯文本还是源代码内注释;是否有 Makefile、批处理脚本或副本?在 README.txt 中粘贴一行;无论您有成熟的单元测试套件还是“黄金文件”测试:
这并不重要。
重要的是您可以尽可能轻松地构建它、测试并使用它。
补充一下个人意见:
KISS。 (保持简短。)
对于小型项目,请使用简单的源代码注释,并且只有当您的规模超过某个点时才开始使用 Doxygen。确保您的文档框架不会使通过全文搜索查找内容变得更困难,因为根据我的经验,除非您真的编写文档,否则人们最终都会这样做> 好吧。
使用简单的 Makefile,仅在必要时使用更复杂的东西(如 CMake、automake 等)。对于小型项目,与“真实”源文件相比,“元数据”的数量可能变得荒谬。
您可以在这个“配角”上投入相当多的时间和精力,在项目开始时,应该将其投入到项目本身中。构建系统、文档等可以根据需要进行增长,但项目架构本身一旦发布就很难重构。这就是您的主要关注点。
Simplify the list:
Whether the docs are HTML, plain text or in-source comments; whether there's a Makefile or a batch script or a copy & paste one-liner in the README.txt; whether you've got a full-blown unit testsuite or a "golden file" test:
It doesn't matter really.
The important thing is that you can build it, test it, and use it as easily as possible.
Adding personal opinion:
KISS. (Keep it short and simple.)
Go with simple source comments for small projects, and only start the Doxygen stuff when you grow beyond a certain point. Make sure your documentation framework doesn't make it harder to find things via full-text search, because in my experience, that's what people end up doing unless you wrote your docs really well.
Go with a simple Makefile and use more sophisticated stuff (like CMake, automake etc.) only when it becomes necessary. For small projects, the amount of "metadata" in comparison to "real" source files can become ridiculous.
You can sink quite some time and energy in this "supporting cast", which - in the beginning of a project - should be put into the project itself. Build system, documentation etc. can grow as necessary, but the project architecture itself is a bitch to refactor once it's been released. That's where your primary focus should be.