※ 引述《[email protected] (海星)》之铭言： : ※ 引述《[email protected] (风起鹰扬)》之铭言： : : 我之前曾在 source code 里面，用 javadoc 那种方式来写注解 (硬写的 XD 见 : : docs/proto/) 当时的想法是，我帮我看懂的 code 注解一下，之後的人就不必重 : : 新去理解 (当然太 detail 或是已经很 trivial 的东西就不必了)。不过後来好像 : : 只有我在写，我也一段时间没碰了，所以没新东西 :p : : (我这里指的文件都是指开发人员需要看的部分。) : 　　我觉得开发上所需要的document，并不是注解或者像javadoc那 : 些东西可以解决的。除了一些本身比较古怪的code，ptt的程式并不 : 算难看懂了。 我觉得问题在於，我可能想改某个 component 中的一个地方，在没有文件的 情况下，我可能得把整个子系统看懂。所以有人看懂的子系统，很多都有文 件 (也许不够完整?) 。另外有些 function 可能有副作用，或是名字没取好 之类的问题。当时是因为这些原因，才想加上这类的注解。结果後来觉得有 的加有的不加不太统一，就加了不少 ^^; : 　　真正需要的是一个跨程序跨模组的说明文件。举个例，水球系统 : ，在哪个程序触发启动，哪个程序编辑讯息，哪个程序收信息，水球 : 资料放在哪里，以怎样的格式，整个流程是怎样？其实不少功能都分 : 布在不同档案不同函数里，而且运作方式也不容易理解，跟踪程式流 : 程和理解其运作方法就花了大部份时间，真正动手修改相较之下反而 : 十分简单。所以我觉得独立的说明文件对开发最有帮助，程式里的注 : 解次之。 这倒是，有些档名跟演化到现在的功能多少有些出入了。还有 bbs.c 里面东西 真的很乱... 还有 include/pttstruct.h ...!@#!@#!@# 但是整个系统有的没 的功能太多了，想写这种文件可能得花点工夫分类、整理一下。 有人想写点东西吗? :) -- May the source be with you. --

※ 发信站: 批踢踢实业坊(ptt.cc) ◆ From: 140.112.244.208