I have designed a web app, this application contains not only some complex controllers, models and views but also some custom libraries and a database.
我设计了一个web应用程序，这个应用程序不仅包含一些复杂的控制器、模型和视图，还包括一些自定义库和数据库。
On top of this there is an ajax layer so: javascript functions and their related server side functions.
除此之外，还有一个ajax层so: javascript函数及其相关的服务器端函数。
I've developed this app by myself and I want some way to ensure that 1 year down the line, if someone else picks it up there is some reference to the logic flow.
我自己开发了这个应用程序，我想找到一种方法来确保1年后，如果有人拿起它，会有一些对逻辑流的引用。
Are there tools for this? Has anyone had this issue before?
有这样的工具吗?以前有人有过这个问题吗?
3 个解决方案
#1
2
A good beginning would be to start using PHP Documentor (PHPDoc) before your code base gets too large. Even then, it's not too hard to go back and tag your classes, etc. PHPDoc will crawl the code base and produce documentation, typically a web-based (HTML) set of docs, but you can also produce PDF and more. The functions, methods, classes, etc. will have links to related elements of your code. I say before it gets too large, because you will want to go back and add comment tags to enhance the output of the documents. PHPDocumentor (PHPDoc) can be found here http://www.phpdoc.org/ , and information and tutorials can be found all over the web. If you have gone this far with PHP then surely you must have noticed comments like this...(doc blocks)
一个好的开始应该是在代码库变得太大之前开始使用PHP Documentor (PHPDoc)。即使这样，返回并标记类也不是很难。PHPDoc将抓取代码库并生成文档，通常是基于web的(HTML)文档集，但您也可以生成PDF等文档。函数、方法、类等将具有与代码相关元素的链接。我说在它变得太大之前，因为您将希望返回并添加注释标记以增强文档的输出。PHPDocumentor (PHPDoc)可以在http://www.phpdoc.org/找到，信息和教程可以在整个web上找到。如果你用PHP做了这么多，那么你一定注意到了这样的评论……(doc块)
/**
*@todo something I need to do
*@param [type] [$varname] [description]
*
*/
These tags/DocBlocks are to be parsed by PHPDoc, and are very useful...Most IDE's too are very friendly to using DocBlocks and will sometimes enhance code hinting, etc. based on the DocBlocks in your code.
这些标签/ docblock将由PHPDoc解析，非常有用……大多数IDE也非常适合使用docblock，并且有时会基于代码中的docblock来增强代码提示等等。
For the Database...there are many tools and teqniques but here is one suggestion...
为数据库……有很多工具和工具，但这里有一个建议……
The database can be described by tools that will build diagrams. For instance, when using MySQL, you could install MySQL Workbench, and this will then give you the tools to connect to the database and build a diagram similar to the picture on this page... http://forge.mysql.com/wiki/MySQL_Workbench, plus many other tools for reverse-enginerring and/or designing, tools for ORM, and more. Sometimes to just diagram and existing DB can be very useful especially when there are many relationships. MySQL Workbench will give you the option to send the diagram to PDF or an image. All very useful.
数据库可以通过构建图表的工具来描述。例如，当你使用MySQL时，你可以安装MySQL Workbench，这将给你提供连接到数据库的工具，并构建一个类似于本页图片的图表……http://forge.mysql.com/wiki/MySQL_Workbench，以及许多其他用于反enginerring和/或设计的工具，ORM工具等等。有时候，仅仅是图和现有的DB就非常有用，特别是当有很多关系时。MySQL Workbench可以为您提供将图表发送到PDF或图像的选项。都很有用。
Not only will this help future developers, but these tools will help yourself too. We're all surprised to realize what we forget after a few weeks, months, etc. of not looking at the code. Even a busy weekend can make for a slow start again on Monday morning.
这不仅将帮助未来的开发人员，而且这些工具也将帮助您自己。我们都很惊讶地发现，在几个星期、几个月之后，我们忘记了什么。即使是一个忙碌的周末，周一早上也会有一个缓慢的开始。
For my last suggestion...and I will be simple here, but look into bug/issue tracking. There are many online or you can install your own. Some go along with version control (like at GitHub, Unfuddle, BitBucket, etc.)...or you can install your own. I find Bugzilla is pretty easy to install if your using Ubuntu it's right in the repository and installs with ease.
我最后的建议…我在这里简单介绍一下，但是要研究bug/问题跟踪。网上有很多，你也可以自己安装。有些支持版本控制(如GitHub、Unfuddle、BitBucket等)……或者你也可以自己安装。我发现Bugzilla很容易安装，如果你使用Ubuntu，它就在存储库中，安装起来也很容易。
#2
1
This surely isn't the whole answer you are looking for, but what I always find very useful is a proper documentation! And yes there are some really good tools like PHPDoc for example. This does partly allow you to create a documentation of the workflow, at least to explain what exactly you are doing.
这肯定不是您正在寻找的全部答案，但是我发现非常有用的是一个合适的文档!确实有一些很好的工具比如PHPDoc。这在一定程度上允许您创建工作流的文档，至少可以解释您正在做什么。
Further down the line you might just explain in plain english how it flows. If it is a really big application, you could even think of creating your own wiki!
你可以用简单的英语解释它是如何流动的。如果它是一个非常大的应用程序，您甚至可以考虑创建您自己的wiki!
#3
1
This is generally known as "as-built" documentation; there's a wealth of information on the interwebs.
这通常称为“已构建”文档;互联网上有丰富的信息。
My preference is to split the documentation into several sections; each is as important as the other, but you don't need to spend equal amounts of time on them.
我倾向于将文档分成几个部分;每一个都和另一个一样重要，但是你不需要在它们上花费同样的时间。
Functional design
功能设计
What's the application supposed to do? What is expected behaviour? What are the key user journeys?
应用程序应该做什么?期望的行为是什么?用户的主要旅程是什么?
I like to use use cases or user stories for this, at varying levels of detail. A system context diagram also helps. Use cases can be both visual and textual; a couple of hours is often enough to describe a simple application
我喜欢使用用例或用户故事，在不同的细节级别。系统上下文关系图也有帮助。用例可以是可视的，也可以是文本的;几个小时通常就足够描述一个简单的应用程序了
Non-functional requirements
非功能性需求
Things like security, performance, browser support, SEO, accessibility - listing the things you have and have not accommodated in the application, so future developers know what to worry about and what to test for.
比如安全性、性能、浏览器支持、SEO、可访问性——列出你在应用程序中所拥有的和没有适应的东西，这样未来的开发人员就知道该担心什么，该测试什么。
Conceptual design
概念设计
A high-level overview of the system as built, identifying the major components, integration points, and dependencies.
系统的高级概览，用于构建、识别主要组件、集成点和依赖项。
Detailed design
详细设计
This is the bit that is most subject to change, and the biggest pain to maintain. Using PHPDoc is a great way of keeping this up to date.
这是最容易改变的部分，也是最难维持的部分。使用PHPDoc是一个很好的方式来保持这个最新。
Acceptance tests
验收测试
Even if you don't buy into Test-Driven Development, leaving future developments with ways of testing that the application works is a great way to keep them sane. Ideally, acceptance tests would be automated/scripted (e.g.using Selenium).
即使您不支持测试驱动的开发，也可以使用应用程序工作的测试方法来开发未来的开发，这是保持它们正常运行的好方法。理想情况下，验收测试将是自动的/脚本化的(例如使用Selenium)。
Known bugs
已知的错误
Providing a list of known bugs to future developers stops them from pulling out their hair...
向未来的开发人员提供一份已知的错误列表，阻止他们拔头发……
All of this can be a lot of work - so many teams use "low-formality' ways of communicating - wikis, photos of whiteboards, even video with the team explaining the design.
所有这些都需要大量的工作——许多团队使用“低形式”的交流方式——维基、白板照片，甚至是团队解释设计的视频。
More formally, there are standards like UML to help capture documentation in an industry standard way.
更正式地说，有像UML这样的标准来帮助以行业标准的方式捕获文档。
#1
2
A good beginning would be to start using PHP Documentor (PHPDoc) before your code base gets too large. Even then, it's not too hard to go back and tag your classes, etc. PHPDoc will crawl the code base and produce documentation, typically a web-based (HTML) set of docs, but you can also produce PDF and more. The functions, methods, classes, etc. will have links to related elements of your code. I say before it gets too large, because you will want to go back and add comment tags to enhance the output of the documents. PHPDocumentor (PHPDoc) can be found here http://www.phpdoc.org/ , and information and tutorials can be found all over the web. If you have gone this far with PHP then surely you must have noticed comments like this...(doc blocks)
一个好的开始应该是在代码库变得太大之前开始使用PHP Documentor (PHPDoc)。即使这样，返回并标记类也不是很难。PHPDoc将抓取代码库并生成文档，通常是基于web的(HTML)文档集，但您也可以生成PDF等文档。函数、方法、类等将具有与代码相关元素的链接。我说在它变得太大之前，因为您将希望返回并添加注释标记以增强文档的输出。PHPDocumentor (PHPDoc)可以在http://www.phpdoc.org/找到，信息和教程可以在整个web上找到。如果你用PHP做了这么多，那么你一定注意到了这样的评论……(doc块)
/**
*@todo something I need to do
*@param [type] [$varname] [description]
*
*/
These tags/DocBlocks are to be parsed by PHPDoc, and are very useful...Most IDE's too are very friendly to using DocBlocks and will sometimes enhance code hinting, etc. based on the DocBlocks in your code.
这些标签/ docblock将由PHPDoc解析，非常有用……大多数IDE也非常适合使用docblock，并且有时会基于代码中的docblock来增强代码提示等等。
For the Database...there are many tools and teqniques but here is one suggestion...
为数据库……有很多工具和工具，但这里有一个建议……
The database can be described by tools that will build diagrams. For instance, when using MySQL, you could install MySQL Workbench, and this will then give you the tools to connect to the database and build a diagram similar to the picture on this page... http://forge.mysql.com/wiki/MySQL_Workbench, plus many other tools for reverse-enginerring and/or designing, tools for ORM, and more. Sometimes to just diagram and existing DB can be very useful especially when there are many relationships. MySQL Workbench will give you the option to send the diagram to PDF or an image. All very useful.
数据库可以通过构建图表的工具来描述。例如，当你使用MySQL时，你可以安装MySQL Workbench，这将给你提供连接到数据库的工具，并构建一个类似于本页图片的图表……http://forge.mysql.com/wiki/MySQL_Workbench，以及许多其他用于反enginerring和/或设计的工具，ORM工具等等。有时候，仅仅是图和现有的DB就非常有用，特别是当有很多关系时。MySQL Workbench可以为您提供将图表发送到PDF或图像的选项。都很有用。
Not only will this help future developers, but these tools will help yourself too. We're all surprised to realize what we forget after a few weeks, months, etc. of not looking at the code. Even a busy weekend can make for a slow start again on Monday morning.
这不仅将帮助未来的开发人员，而且这些工具也将帮助您自己。我们都很惊讶地发现，在几个星期、几个月之后，我们忘记了什么。即使是一个忙碌的周末，周一早上也会有一个缓慢的开始。
For my last suggestion...and I will be simple here, but look into bug/issue tracking. There are many online or you can install your own. Some go along with version control (like at GitHub, Unfuddle, BitBucket, etc.)...or you can install your own. I find Bugzilla is pretty easy to install if your using Ubuntu it's right in the repository and installs with ease.
我最后的建议…我在这里简单介绍一下，但是要研究bug/问题跟踪。网上有很多，你也可以自己安装。有些支持版本控制(如GitHub、Unfuddle、BitBucket等)……或者你也可以自己安装。我发现Bugzilla很容易安装，如果你使用Ubuntu，它就在存储库中，安装起来也很容易。
#2
1
This surely isn't the whole answer you are looking for, but what I always find very useful is a proper documentation! And yes there are some really good tools like PHPDoc for example. This does partly allow you to create a documentation of the workflow, at least to explain what exactly you are doing.
这肯定不是您正在寻找的全部答案，但是我发现非常有用的是一个合适的文档!确实有一些很好的工具比如PHPDoc。这在一定程度上允许您创建工作流的文档，至少可以解释您正在做什么。
Further down the line you might just explain in plain english how it flows. If it is a really big application, you could even think of creating your own wiki!
你可以用简单的英语解释它是如何流动的。如果它是一个非常大的应用程序，您甚至可以考虑创建您自己的wiki!
#3
1
This is generally known as "as-built" documentation; there's a wealth of information on the interwebs.
这通常称为“已构建”文档;互联网上有丰富的信息。
My preference is to split the documentation into several sections; each is as important as the other, but you don't need to spend equal amounts of time on them.
我倾向于将文档分成几个部分;每一个都和另一个一样重要，但是你不需要在它们上花费同样的时间。
Functional design
功能设计
What's the application supposed to do? What is expected behaviour? What are the key user journeys?
应用程序应该做什么?期望的行为是什么?用户的主要旅程是什么?
I like to use use cases or user stories for this, at varying levels of detail. A system context diagram also helps. Use cases can be both visual and textual; a couple of hours is often enough to describe a simple application
我喜欢使用用例或用户故事，在不同的细节级别。系统上下文关系图也有帮助。用例可以是可视的，也可以是文本的;几个小时通常就足够描述一个简单的应用程序了
Non-functional requirements
非功能性需求
Things like security, performance, browser support, SEO, accessibility - listing the things you have and have not accommodated in the application, so future developers know what to worry about and what to test for.
比如安全性、性能、浏览器支持、SEO、可访问性——列出你在应用程序中所拥有的和没有适应的东西，这样未来的开发人员就知道该担心什么，该测试什么。
Conceptual design
概念设计
A high-level overview of the system as built, identifying the major components, integration points, and dependencies.
系统的高级概览，用于构建、识别主要组件、集成点和依赖项。
Detailed design
详细设计
This is the bit that is most subject to change, and the biggest pain to maintain. Using PHPDoc is a great way of keeping this up to date.
这是最容易改变的部分，也是最难维持的部分。使用PHPDoc是一个很好的方式来保持这个最新。
Acceptance tests
验收测试
Even if you don't buy into Test-Driven Development, leaving future developments with ways of testing that the application works is a great way to keep them sane. Ideally, acceptance tests would be automated/scripted (e.g.using Selenium).
即使您不支持测试驱动的开发，也可以使用应用程序工作的测试方法来开发未来的开发，这是保持它们正常运行的好方法。理想情况下，验收测试将是自动的/脚本化的(例如使用Selenium)。
Known bugs
已知的错误
Providing a list of known bugs to future developers stops them from pulling out their hair...
向未来的开发人员提供一份已知的错误列表，阻止他们拔头发……
All of this can be a lot of work - so many teams use "low-formality' ways of communicating - wikis, photos of whiteboards, even video with the team explaining the design.
所有这些都需要大量的工作——许多团队使用“低形式”的交流方式——维基、白板照片，甚至是团队解释设计的视频。
More formally, there are standards like UML to help capture documentation in an industry standard way.
更正式地说，有像UML这样的标准来帮助以行业标准的方式捕获文档。