10

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 的艺术字一样）。现在我为主窗口编写了代码（在 .Net 中使用 WPF，或者在 Java 中使用 Window Builder，无论使用哪种工具/语言）。

现在，如果我的同事 Spongebob 先生正在编写艺术字部分，我将如何告诉他要调用哪些函数 / Api 用于在我的窗口上绘图？即如何让海绵宝宝知道他需要调用GetWindow()方法来获取绘图表面的引用、他需要传递的参数等等？

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

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

第 2 步：编写GetWindow()方法，使其与项目的其余部分一起工作

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

第 3 步：现在你的同事海绵宝宝很头疼如何找到如何在我的窗口上绘制他的艺术字。

这听起来不对……海绵宝宝的功能很多，就像我的一样。我们俩都在翻阅文档以找到合适的功能来完成我们的工作。如果那我改变GetWindow() to GetWindow(string title)了怎么办.. 现在我literally tell这个可怜的海绵宝宝怎么办呢？他需要重做他的代码。

我在这里错过了什么吗？请分享您的经验，您如何在现实世界的软件公司环境中解决这个问题？如果你的开发伙伴在下一张桌子上，你真的会展示吗？他们展示了当他们卡住时如何实现某种方法，或者您如何处理这种情况？谢谢你

谢谢

4

8 回答 8

6

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

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

于 2013-04-27T10:37:37.440 回答
4

Wiki 是一个绝妙的主意（好建议@Micha！）。我曾经在以前的公司使用过一个大型工程软件/硬件项目。它显然涵盖了硬件和软件人员，因此这是在所有团队之间共享信息的好方法。如果它也是一个长期项目，它真的很有用——你可以跟踪功能/API 的变化，因为随着时间的推移，事情不可避免地会发生变化。

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

不过，另一方面，您是否考虑过自我记录代码？例如“Doxygen”或类似的？为记录每个单独的功能付出了很多痛苦，并且还建立了一个体面的框架，可以在必要时添加更多信息。它还创建了一个很好的用户界面，用于单步执行所有功能/类等。

编辑：我实际上刚刚开始使用 Google 协作平台 (sites.google.com) 为我不合作的开发团队创建一个 wiki。它是免费的（就像在“啤酒”中一样），到目前为止看起来还不错，尽管它确实缺少自动代码格式化。

于 2013-04-27T11:36:07.747 回答
3

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

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

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

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

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

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

希望有帮助。

于 2013-05-15T12:43:27.877 回答
2

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

//======
//
//  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 软件，提及最重要的内容而不浪费太多时间在文档上是一个不错的选择。

于 2013-05-16T13:45:45.597 回答
0

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

您的文档也可以在 wiki 中，然后您可以简单地向 Spongebob 发送链接。

于 2013-05-16T04:25:59.337 回答
0

对于初学者：

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

如果然后我将 GetWindow() 更改为 GetWindow(string title).. 现在我该如何告诉可怜的海绵宝宝他需要重做他的代码。

您应该始终以“获取最新”开始您的一天编码，这意味着从存储库下载代码。如果海绵宝宝这样做，他会立即看到他现在需要传入字符串标题，因为他的代码将停止编译。最好直接告诉海绵宝宝你已经改变了你的代码，他现在需要传入一个值，但是如果你每天晚上都检查代码，并且在你开始编码的时候获取最新的代码，那么你应该都被告知.

至于使用 WIKI 还是使用 Sharepoint 无关紧要。我想说让它更有效率为什么不这样做：

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

有关此访问的更多信息，请访问__网站： http ://yourrespositoryname.com/nameofprocedure

于 2013-05-16T15:36:32.170 回答
0

你为什么不把你的工作放在一个 git/svn 项目中，而不是独立地处理项目部分呢？然后，当您更改核心函数时，您将看到它破坏了什么，并负责在提交更改之前修复调用它的方法。

我不喜欢在开发过程中大量记录。它让你放慢了太多，你将不得不一遍又一遍地重做。只需创建描述性的方法名称，并在代码中提供大量注释。

于 2013-05-16T15:00:39.717 回答
0

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

于 2013-05-16T14:06:50.987 回答