如何记录您的申请？ [英] How do you document your application?

问题描述

我从来不知道如何以其他开发人员发现它易于使用和/或维护系统的方式记录系统。记录源代码是很好的，但是我不认为这是很好的概述应用程序本身。

Java似乎保持最多的源代码中的文档，仅描述某些类的基本用法 - 创建一个 DecimalFormat 对象用于使用逗号作为小数分隔符是不重要的，如果你只是（通常很详细）的API文档（根据我的理解从他们的文档）涉及 DecimalFormatSymbols 和 Locale 类，但重点是：我无法确定没有进一步的信息）。然后，这些缺少的部分被单独的 Java教程，它们主要描述他们的库的不同的特殊用例。

另一方面，Ogre3d图形引擎创建了特殊页面，用于其应用程序的一般描述，可作为食人魔手册获得，他们试图解释我们知道图书馆的范围在这里是不一样的，我不是在抨击Java，而是认为这将是一个可取之地。文档哲学的比较。

我们最近开始将我们所有的文档放入我们公司的源代码中，这让我想起：他人如何记录他们的应用程序，如何为他们工作（或更重要的是：为其他开发商加入他们的项目）？

编辑

我想我需要澄清有一点：当一个项目超过一定（代码/团队）的大小时，其他开发人员就很难加入。我知道代码文档对于了解代码是非常重要的，但是我不认为开始使用该项目是足够的。别人必须给他一个教程（解释为什么东西看起来像他们这样做），或者需要在某个地方记录。

所以实际的问题是：什么您向新开发人员提供文档，对他们有用吗？他们阅读了200页系统文档吗？他们首先潜入代码吗？阅读后，他们要问多少问题？

我不是在你的同事的反应之后，而是文档过程的效率（只是提到作为指标的反应）。

解决方案

首先，这似乎很明显，但并不是很多人似乎遵循它写的<一个href =http://en.wikipedia.org/wiki/Self-documenting =nofollow noreferrer>自我记录代码。

其次，重构代码使其更容易阅读 - 这个典型的例子是提取方法重构。

第三，这似乎很明显 - 如果你编写JavaDoc样式的评论，去舷外在之前的公司中，我的一个同事看着别人的代码，这些代码被大量记录，只是发现文档与代码正在做的完全相反。如果你要大量地记录代码，那么确保它与代码生活是非常重要的。人们经常记录代码，更改它，然后不更新文档。如果我绊倒.NET代码，记录不良，我通常会使用反射器获取更好地了解发生了什么。

最后人们忘记单元测试也可以作为文档。

I never know how to document a system in a way that other developers will find it easy to use and/or maintain it. Documentating the source code is good and required for that, but I don't think it is enough to give a good overview of the application itself.

Java seems to keep most of its documentation in the source code, which describes only basic usage of certain classes - creating a DecimalFormat object for using a comma as the decimal separator is non-trivial if you stik to the (generally quite verbose) API documentation only (as far as I understood from their documentation it involves the DecimalFormatSymbols and Locale classes, but the point is: I can't tell for sure without further information). The missing parts are then tried to be covered by separate Java tutorials, which mostly describe distinct special use cases of their library.

The Ogre3d graphics engine, on the other hand, created special pages for the general description of their application, which is available as the ogre manual and they try to explain the wholeness of their engine there.

I know, the scope of the libraries are not the same here, and I'm not bashing Java, but thought it would be an appropriote comparison of documentation philosophies.

We recently started putting all our documentation into the source code in our company, which made me wonder: How do others document their applications and how does it work out for them (or more importatly: for other developers joining their project)?

EDIT

I guess I need to clarify a bit: When a project grows beyond a certain (code-/team-) size it gets hard for other developers to join it. I know that code documentation is very important for them to understand the code, but I don't think it is sufficient to get started working on the project. Either someone else has to give him a tutorial (explaining why things look the way they do), or it needs to be documented somewhere.

So the actual question is: What documentation do you provide to new developers and how useful is it to them? Do they read the 200-Page system documentation? Do they dive into the code first? How many and what kind of questions do they ask after reading them?

I'm not after the reactions of your colleagues, but the efficiency of your documentation process (just mentioning the reactions as an indicator).

解决方案

Firstly, and this seem obvious but not many people seem to follow it well- write self-documenting code.

Secondly refactor the code to make it easier to read- the classic example of this is the Extract Method refactoring.

Thirdly and this seems obvious- if you do write JavaDoc style comments, don't go overboard. In a previous company one of my coworkers looked at someone else's code which was heavily documented, only to find the documentation was the exact opposite of what the code was doing. If you are going to heavily document code then it is important to make sure it "lives" with the code.

All too often people document the code, change it and then don't update the documentation. If I stumble across .NET code that is badly documented I usually use Reflector to get a better understand of what is going on.

Finally people forget that unit tests can also act as documentation.

这篇关于如何记录您的申请？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！