in private and in companies it is over and over again a problem that I or we developers comment in fact our code but generally nobody knows exactly how the code of the whole project works together. When I write my own code and the project is getting bigger I sometimes have this problem too. Although I write tons of comments, after 3 months you don't know what the whole thing exactly does, that means how the different methods and classes work together.
How do you solve this in your company or in private (if there is just marginal project development and no requirements specification). Or do you have always such a good project development with contract document and requirements specification that you don't have to worry about that?
在私人和公司中,我或我们的开发人员一遍又一遍地评论我们的代码,但一般没人知道整个项目的代码是如何协同工作的。当我编写自己的代码并且项目越来越大时,我有时也会遇到这个问题。虽然我写了大量的评论,但是3个月后你不知道究竟是什么,这意味着不同的方法和类如何协同工作。您如何在公司或私人中解决这个问题(如果只是边际项目开发而没有要求规范)。或者您是否总是通过合同文件和要求规范进行如此好的项目开发,而您不必担心这一点?
4 个解决方案
#1
4
Code complete can explain the solution to your problem better than I ever could.
代码完整可以比我更好地解释您的问题的解决方案。
#2
3
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.
如果记录起来听起来太难了,那么重构代码的时间就是这样。
#3
1
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.
花点时间创建一些简短的设计文档,添加一些UML图表来展示整个应用程序背后的基本思想。这将为新的团队成员提供快速概览。在内部维基上发布此文档,并鼓励团队在必要时进行增强。
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 ;-) )
然后,正如彼得所建议的那样,一些记录良好的测试用例确实有帮助:阅读测试代码并学习如何使用API。 (并且,作为次要影响,测试代码;-))
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.
我不会在评论上投入太多精力,特别是在线评论。往往会过时,因为没有单元测试验证行注释仍然有效,甚至值得,没有人删除不必要的注释。
#4
1
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.
我不能强调编写清晰可维护代码的重要性。最近,当我阅读Robert Martin的清洁代码时,我的眼睛才被打开。您应该自己和您的开发人员至少阅读本书前几章的内容。仅此一项就可以立即提高代码的可读性和可维护性。
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.
这个想法是代码应该读起来几乎像一个叙述,其中方法遵循逻辑顺序,简短,适当命名,并采取一些参数。这样做几乎消除了对代码注释的需要,并改进了代码结构。
#1
4
Code complete can explain the solution to your problem better than I ever could.
代码完整可以比我更好地解释您的问题的解决方案。
#2
3
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.
如果记录起来听起来太难了,那么重构代码的时间就是这样。
#3
1
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.
花点时间创建一些简短的设计文档,添加一些UML图表来展示整个应用程序背后的基本思想。这将为新的团队成员提供快速概览。在内部维基上发布此文档,并鼓励团队在必要时进行增强。
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 ;-) )
然后,正如彼得所建议的那样,一些记录良好的测试用例确实有帮助:阅读测试代码并学习如何使用API。 (并且,作为次要影响,测试代码;-))
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.
我不会在评论上投入太多精力,特别是在线评论。往往会过时,因为没有单元测试验证行注释仍然有效,甚至值得,没有人删除不必要的注释。
#4
1
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.
我不能强调编写清晰可维护代码的重要性。最近,当我阅读Robert Martin的清洁代码时,我的眼睛才被打开。您应该自己和您的开发人员至少阅读本书前几章的内容。仅此一项就可以立即提高代码的可读性和可维护性。
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.
这个想法是代码应该读起来几乎像一个叙述,其中方法遵循逻辑顺序,简短,适当命名,并采取一些参数。这样做几乎消除了对代码注释的需要,并改进了代码结构。