I find the best way to solve this is to write a functional test using a unit test framework.
In a functional test you write a test which loads up several if not all the core components laid bare. This shows that all the components work correctly together but also you get a documents which shows you in one place how everything connects.
Depending on how complex you interactions are, you may not be enough and you need to document it. Personally I would prefer to make the code simple so that documenting it is not really needed or is relatively easy to explain.
If documenting it sounds too hard, its time to refactor your code so that its not.
Take your time a create some short and simple design documents, add some UML diagrams to just show the basic ideas behind the whole application. This would give new team players a quick overview. Publish this documentation on an internal wiki and encourage the team to enhance, if necessary.
Then, as Peter suggested, some well documented test cases really help: Read the test code and learn how to use the API. (and, as a secondary effect, test the code ;-) )
I would not put too much effort on comments, especially on line comments. The tend to become out dated, because no unit test verifies that line comments are still valid and, even worth, no one ever deletes unnecessary comments.
Good question. Part of what you are asking relates to code maintainability. In my view the two main things you can do to improve this are:-
Write some design documentation
Develop maintainable and clearly written code
From past experience the first item is very often neglected on software projects due to time constraints, but I think that if you can produce at least a class diagram of your system, then this is worth a lot in terms of understanding how objects interract when you revisit the code in a few months. Depending on the complexity, then sequence diagrams can also be useful. Producing this documentation will also be of benefit to new members of the team, in quickly having an overview of how the software is structured.
I can't stress enough the importance of writing clear and maintainable code. My eyes were recently opened when I read Clean Code by Robert Martin. You owe it to yourself and your fellow developers to read at least the first couple of chapters in this book. That alone will immediately improve the readability and maintainability of your code.
The idea is that the code should read almost like a narrative, where methods follow in a logical order, are short, appropriately named, and take few parameters. Doing this almost eliminates the need for code comments, and improves the code structure.
发布评论
评论（4）
代码完整可以比我更好地解释您的问题的解决方案。
Code complete can explain the solution to your problem better than I ever could.
我发现解决这个问题的最佳方法是使用单元测试框架编写功能测试。
在功能测试中，您编写一个测试，该测试会加载几个（如果不是全部）裸露的核心组件。这表明所有组件都可以正确地协同工作，而且您还可以获得一份文档，其中在一个位置向您展示了所有组件如何连接。
根据交互的复杂程度，您可能还不够，需要将其记录下来。就我个人而言，我更喜欢使代码简单，这样就不需要记录它，或者相对容易解释。
如果记录它听起来太难了，那么是时候重构你的代码了，这样就不会了。
I find the best way to solve this is to write a functional test using a unit test framework.
In a functional test you write a test which loads up several if not all the core components laid bare. This shows that all the components work correctly together but also you get a documents which shows you in one place how everything connects.
Depending on how complex you interactions are, you may not be enough and you need to document it. Personally I would prefer to make the code simple so that documenting it is not really needed or is relatively easy to explain.
If documenting it sounds too hard, its time to refactor your code so that its not.
花点时间创建一些简短的设计文档，添加一些 UML 图来展示整个应用程序背后的基本思想。这将使新团队成员能够快速了解情况。在内部 wiki 上发布此文档并鼓励团队在必要时进行增强。
然后，正如 Peter 所建议的，一些记录良好的测试用例确实有帮助：阅读测试代码并学习如何使用 API。 （并且，作为次要效果，测试代码;-)）
我不会在注释上投入太多精力，尤其是在行注释上。它们往往会过时，因为没有单元测试验证行注释仍然有效，甚至值得，没有人删除不必要的注释。
Take your time a create some short and simple design documents, add some UML diagrams to just show the basic ideas behind the whole application. This would give new team players a quick overview. Publish this documentation on an internal wiki and encourage the team to enhance, if necessary.
Then, as Peter suggested, some well documented test cases really help: Read the test code and learn how to use the API. (and, as a secondary effect, test the code ;-) )
I would not put too much effort on comments, especially on line comments. The tend to become out dated, because no unit test verifies that line comments are still valid and, even worth, no one ever deletes unnecessary comments.
好问题。您所要求的部分内容与代码可维护性有关。在我看来，你可以做两件主要的事情来改进这一点： -
根据过去的经验，由于时间限制，第一项在软件项目中经常被忽视，但我认为如果你至少可以生成系统的类图，那么这对于理解几个月后重新访问代码时对象如何交互而言非常有价值。根据复杂性，序列图也很有用。制作此文档对于团队的新成员也有好处，可以快速了解软件的结构。
编写清晰且可维护的代码的重要性怎么强调都不为过。最近，当我阅读 干净的代码 作者：Robert Martin。为了你自己和你的开发伙伴，你至少应该阅读本书的前几章。仅此一点就可以立即提高代码的可读性和可维护性。
这个想法是，代码应该读起来几乎像一个叙述，其中方法按逻辑顺序排列，简短，命名适当，并且采用很少的参数。这样做几乎消除了代码注释的需要，并改进了代码结构。
Good question. Part of what you are asking relates to code maintainability. In my view the two main things you can do to improve this are:-
From past experience the first item is very often neglected on software projects due to time constraints, but I think that if you can produce at least a class diagram of your system, then this is worth a lot in terms of understanding how objects interract when you revisit the code in a few months. Depending on the complexity, then sequence diagrams can also be useful. Producing this documentation will also be of benefit to new members of the team, in quickly having an overview of how the software is structured.
I can't stress enough the importance of writing clear and maintainable code. My eyes were recently opened when I read Clean Code by Robert Martin. You owe it to yourself and your fellow developers to read at least the first couple of chapters in this book. That alone will immediately improve the readability and maintainability of your code.
The idea is that the code should read almost like a narrative, where methods follow in a logical order, are short, appropriately named, and take few parameters. Doing this almost eliminates the need for code comments, and improves the code structure.