Question

我即将结束今年夏天的实习，我为我的导师开发了一个主要涉及PHP，MySQL，JavaScript（jQuery）的工具。有没有人有关于创建易于阅读的文档的任何模板或建议或链接，显示程序的代码结构和文件之间的关系？

这些人是程序员，但在上述任何一种语言中都没有太多经验，所以我希望它相对简单。

编辑：

似乎某种类型的流程图是要走的路（这是有道理的）。你是从页面上的每个类文件开始的吗？或者你是一个一个地开始，找出每一个细节并分出来，重新整理它，因为它变得更复杂。

Answer 1

思维导图可能会有所帮助，我可以推荐一些免费工具，例如FreeMind或XMind或iMindq

Answer 2

我首先描述软件的功能（功能规范），以及如何构建，运行和测试它：How does a good developer keep from creating code with a low bus hit factor?

完成之后，您可以将函数规范中的指针添加到源代码中，以确定哪些源代码有助于实现哪些功能。

[当我说'指针'时，我的意思是在标识/描述某些功能的部分中，添加相应源代码的URL和/或名称。]

Answer 3

您可以查看Doxygen，它标记了PHP文档。如果dot可用，Doxygen可以自动生成文件的依赖图，函数的调用图和类的祖先图。

但是，Doxygen对记录MySQL源没有任何确切的支持。看来，有一些流行的perl脚本用于记录Javascript代码。

您可能也有兴趣看到some sample Doxygen-generated documentation。

Answer 4

搜索任何免费的UML工具，或者如果您有权访问Microsoft Visio，则使用它来创建UML图。

Answer 5

我建议使用OmniGraffle。它是一个OS X应用程序，但它是现象。

http://www.omnigroup.com/applications/OmniGraffle/

Answer 6

我为很多项目做过这个。事实上，现在当我开始研究现有的工作时，我已经学会了制作某种流程图供我自己参考，然后将其检入存储库。

我更喜欢流程图类型的图表（可能除了您的想法之外）。我只是使用Open Office并绘制圆形，矩形，三角形等，用于各种各样的部分。决定。如果您制作一个然后复制它，根据需要更改文本，这不是太耗时。与箭头相同，只需制作很多箭头，然后将它们移动到您想要的位置。

我已经尝试过寻找能够实现这一目标的工具，但如果它比OO使用起来要容易得多，那么它往往会出现问题并且崩溃。如果它稳定，那就没有任何更快，也许没有像OO那样多的绘图选项。

Answer 7

我使用了免费的PlantUML工具，这个工具还有一个用于eclipse的插件以及其他几个插件。有趣的是，关于这个工具，您必须编写一个文本脚本来生成图表，该图表具有许多优点以及一些缺点。例如轻松复制粘贴部分UML图表并快速修改图表，将其与mediawiki等集成。

一些例子

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

和

@startuml
actor Foo1
boundary Foo2
control Foo3
entity Foo4
database Foo5
Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database
@enduml

和

@startuml

User -> (Start)
User --> (Use the application) : A small label

:Main Admin: ---> (Use the application) : This is\nyet another\nlabel

@enduml

和

@startuml

[*] --> State1
State1 --> [*]
State1 : this is a string
State1 : this is another string

State1 -> State2
State2 --> [*]

@enduml

@startuml

object user {
  name = "Dummy"
  id = 123
}

@enduml

所有示例均来自PlantUML official website

编写代码流程图的建议

编辑：

7 个答案: