如何共享项目的代码文档？

Question

这里有一个类似的问题,关于SO /sf/ask/663305681/,但我的是关于写作文档.

场景:

假设我的团队正在开发一个软件项目,一个像Fany-WordPad这样的应用程序,它具有一个名为Fancy-Word-Art的功能(就像MS Office的文字Art).现在我编写了主窗口的代码(在.Net中使用WPF,或者在Java中使用Window Builder,与哪种工具/语言无关).

现在,如果我的同事Spongebob先生正在编写Word-Art部分,我怎么能告诉他在我的窗口上用什么函数来调用/ Api？即如何让SpongeBob先生知道他需要调用GetWindow()方法来获取绘图表面的参考,他需要传递的参数,等等？

我希望我在这里清楚.这是程序吗？

第1步:使用您公司的维基站点了解您同事的书面代码

第2步:编写GetWindow()方法,使其与项目的其余部分一起使用

第2步:现在使用方法的方法参数/数据类型要求在您的Intranet上放置一个wiki,GetWindow()或者使用Doxygen/Confluence,如下所示

第3步:现在你的同事Spongebob先生头疼如何找到如何在我的窗户上画出他的文字艺术.

这听起来不对.随着大量的功能,海绵宝宝的生活将变得艰难,就像我的一样.我们俩都通过文档搜索找到合适的功能来完成我们的工作.如果我改变了GetWindow() to GetWindow(string title)怎么办呢？现在我怎么做literally tell他需要重做他的代码的可怜的海绵宝宝.

我在这里错过了什么吗？请分享您的经验,您如何在现实世界的软件公司环境中解决这个问题？如果您的同事开发人员在下一张桌子上,您是否实际向他们展示了如何实施某种方法,因为他们遇到困难,或者您如何应对这种情况？谢谢

谢谢

Answer 1

一个好问题.当然,我没有通用的解决方案.msdn/sun风格的代码文档是一个很好的基础.但是对于概念,架构等,你需要的不仅仅是这个.在某些项目中,我们使用wiki.对于客户请求,我们有一种票证系统,我们还将一些(无代码)信息存储到解决方案中.总而言之,所有文件都没有中心位置.

编辑:您自己的代码通常是最好的文档,遵循干净的代码指南或其他一些是真正的最佳实践:-)

Answer 2

在我看来，您需要 API 文档和大量示例。

当然，您可能会从记录代码中获得一些好处，但如果您真正正确地编写了系统，您的客户将永远不会看到您的代码。（这适用于呼叫意义上的客户，不一定适用于“为您的服务付费”的意义上）。

这是良好实践和 SOA 的基础，因此您应该真正放弃“自记录代码”方法。

一旦客户“得到它”，函数/方法/属性/任何东西的字母顺序列表就有价值，但在那之前，它不会立即有用。

因此，您必须展示您的创作。给出一堆立即有用的例子来展示你设想的那种事情。确保您有一个简单的示例，以基本形式演示每个功能，并且与系统其余部分的交互最少（所需的交互太多，而且您可能还没有一个干净的系统）。

一旦你有了它，把它放在 Wiki 上并鼓励你的用户增强它。考虑使用类似 Stack-Overflow 的平台等交互式平台。MSDN 是一个很好的模型，但他们的示例通常很糟糕并且缺乏上下文。您可能会拥有比整个 .NET 框架更严格和更具体的用途。尽早回复问题和更新示例/文档将确保您的信息在至关重要的早期得到传达。这将通过照顾您的客户并为他们提供有用的、实际的帮助来帮助您快速减轻文档负担。

希望有帮助。