Question

这里有关于SO https://stackoverflow.com/questions/9475795/how-do-you-share-code-across-teams-working-on-very-different-projects的类似问题，但我的是撰写文档。

情境：

让我们说我的团队正在开发一个软件项目，一个像Fany-WordPad这样的应用程序，它有一个名为 Fancy-Word-Art 的功能（就像MS Office＆＃39; s文字艺术）。现在我编写了主窗口的代码（在.Net中使用WPF，或者在Java中使用Window Builder，并不重要的是哪种工具/语言）。

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

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

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

第2步：编写GetWindow()方法，以便与项目的其余部分配合使用

第2步：现在使用您的GetWindow()方法的方法参数/数据类型要求在您的Intranet上放置一个wiki，或者按照下面的建议使用Doxygen / Confluence

第3步：现在你的同事海绵宝先生很头疼如何找到如何在我的窗户上画出他的文字艺术。

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

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

由于

Answer 1

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

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

Answer 2

维基是一个很好的想法（好建议@Micha！）。我以前在一家公司中使用过一个大型工程软件/硬件项目。它显然跨越了硬件和软件人员，因此这是一种在所有团队之间共享信息的好方法。如果它也是一个长期项目，它真的很有用 - 您可以跟踪功能/ API的变化，因为随着时间的推移不可避免地会发生变化。

如果我没记错的话，我们使用了付费服务 - Confluence;但是也有免费的wiki托管网站，例如wikihost（只是一个快速的谷歌搜索，我不能保证他们）。

另一方面，您是否考虑过自行记录代码？例如“Doxygen”或类似的？记录每一个功能都会带来很多麻烦，并且还会建立一个可以在必要时填充更多信息的体面框架。它还为步进所有函数/类等创建了一个很好的UI。

修改：我实际上刚刚开始使用Google协作平台（sites.google.com）为我未与之合作的开发团队创建Wiki。它是免费的（如'啤酒'）并且到目前为止似乎相当不错，尽管它确实没有自动代码格式化。

Answer 3

IMO您需要API文档和大量示例。

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

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

一个字母的函数/方法/属性列表/一旦客户端“得到它”就有价值但在那之前，它并不是立即有用的。

因此，您必须展示您的创作。给出一堆直接有用的例子，展示你设想的那种东西。确保你有一个简单的例子，它以基本形式演示每个函数，与系统的其余部分进行最少的交互（太多需要的交互，你可能还没有一个干净的系统）。

完成后，将其放在Wiki上并鼓励用户对其进行增强。考虑使用类似Stack-Overflow类平台的交互式东西。 MSDN是一个很好的模型，但他们的例子往往很糟糕，缺乏上下文。与整个.NET框架相比，您可能拥有更紧凑和特定用途的奢侈品。及早回复您的示例/文档的问题和更新将确保您的信息在重要的早期阶段得到体现。这将通过照顾您的客户并为他们提供有用的实用帮助来帮助您快速减轻文档负担。

希望有所帮助。

Answer 4

在我的项目中，我在顶部的类文件中使用了简短描述，例如：

//======
//
//  modul:      fileRunner.cs
//  ...
//  what:       for playing audio/video
//  depends on: consoleOutput.cs (Form)
//
//=======
#region HowToUse
//=======
//
//          HowToUse
//
//      1. create instance of fileRunner:
//          fileRunner p = new fileRunner();
//      2. run console program [progPath] with arguments [cmdsString]
//          string output = p.RunExternalExe(progPath, cmdsString);
//      3. handle [output]
//          if (output == "anyError"){do something;}
//
//  [OUTPUT]
//      "0" : process ended w/o errors
//      "C" : canceled by user
//      else: output is the string of the StdError, the called program submitted + StdOut after "Std output:"
//
//  IMPORTANT
//  Mention, this file depends on consoleOutput.cs to parse the output for gui.
//  It doesn't support input ways, because the way ffmpeg is outputting doesn't allow it, it's not active
//=======
#endregion

对于其他类，我只是命名了自我描述的公共函数。另一个选择是在顶部写下它们应该看起来代码中的注释和公共函数的顶部我使用类似的解释：

#region convert an audio or video file from a drop
// FUNCTION:    convertTo
// DOES:        converting a file from a drop
//              does not delete the original
// INPUT1:      [path] as string, 
//                  path to the destination file
// INPUT2:      [e] as System.Windows.Forms.DragEventArgs,
//                  the args, the drop-object submits
//                  path of source file is in here
// OUTPUT:      isConverted as bool,
//                  true if not (canceled or error raised)
    public bool convertTo(string pWorkingFile, DragEventArgs e)
    {
       ...
    }
#endregion

如果有什么变化，你也可以在顶部提到它。我认为使用SCM软件是一个很好的选择，提到最重要的不会浪费太多时间在文档上。

Answer 5

听起来很愚蠢，我会给他（海绵宝宝）写一封邮件，或者告诉他他需要什么。如果你已经知道谁将在不久的将来需要一些东西，那么如果你能在他们开始搜索并头疼之前通知那些人，那就太棒了。并非项目中的所有内容都需要技术解决方案，人与人之间的关系要好得多。

您的文档也可以在wiki中，然后您只需向Spongebob发送链接即可。

Answer 6

为了减少在大型API上更改规范所涉及的痛苦，我建议您遵循前面提到的msdn / javadoc约定，并建议您的团队伙伴使用具有自动完成/自动提示功能的现代IDE。提供自动建议的大多数常见编辑器还显示要使用的方法/成员的文档。如果你在这里寻求敏捷，那么docs和wiki就有点矫枉过正;我的2美分。

Answer 7

为什么不将您的工作放在一个git / svn项目中，而不是单独处理项目部分？然后，当您更改核心功能时，您将看到它断开了什么，并负责在提交更改之前修复调用它的方法。

我不喜欢在开发过程中广泛记录。它会让你减速太多，你将不得不一遍又一遍地重做它。只需创建描述性的方法名称，并在代码注释中慷慨。

Answer 8

首先：

为了帮助海绵宝宝和你自己一起工作，你需要某种代码资产管理软件（GIT，TFS等）。

如果我将GetWindow（）更改为GetWindow（字符串标题）怎么办？现在我如何告诉他需要重做他的代码的可怜的海绵宝宝。

您应该始终通过“GET LATEST”开始您的一天编码，这意味着从存储库下载代码。如果spongebob这样做，他会立即看到他现在需要传递字符串标题，因为他的代码将停止编译。你最好告诉海绵宝宝，你已经改变了你的代码，他现在需要传递一个值，但是如果你每晚都在检查代码并且当你开始编写当天的最新版本时，你应该得到通知

至于使用WIKI或使用Sharepoint无关紧要。我会说为什么不这样做会更有效率：

在您的文档存储库（Wiki / Sharepoint）中按页面名称调用文件，因此一个是艺术字，另一个是MainDocument，也许一个是PrintDocument（假设这些是不同的页面），在代码中您可以简单地放置：< / p>

有关此内容的详情，请访问 _ __网站：http://yourrespositoryname.com/nameofprocedure

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

8 个答案: