Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

完善项目下的 README/HACKING 文档 #23

Closed
snyh opened this issue Jan 19, 2016 · 5 comments
Closed

完善项目下的 README/HACKING 文档 #23

snyh opened this issue Jan 19, 2016 · 5 comments

Comments

@snyh
Copy link
Member

snyh commented Jan 19, 2016

需要两个基本的文档

HACKING 目前没有模板, 不过主要内容有这些点

  • 文件布局
  • 模块设计
  • TODOs (方便其他人加入)
  • Workarounds (比较反常的行为,提醒时刻记住)

另外如果有些点是比较重要的可以单独写一个文件作为链接加入 HACKING 里面

@snyh
Copy link
Member Author

snyh commented Jan 19, 2016

模块设计可以参考以下方式

1 核心设计

从整体上描述设计内容.内容一般包括,涉及到哪些服务/模块/组件 以及他们的

职责
事件流
异常情况以及对应的事件流
2 图解

通过UML图表的形式来描述设计思想.与"核心设计"配合阐述设计思想的.

常见的图表类型有

用例图 (use case diagram)
类图 (class diagram)
时序图 (sequence diagram)
状态图 (state diagram)
使用哪种图进行描述,可以通过此设计涉及到的关键视角.比如

主题是数据模型的建立,就采用 class diagram + ER diagram
主题是消息/数据的流通,就采用 sequence diagram
主题是部署,配置之类的就采用 deployment diagram
主题是模块之间的关系,就采用 use case diagram
主题是几种状态间的切换,就采用 sate diagram
若是不太熟悉UML的使用,推荐在这里入门 若是没有合适的UML编写工具,推荐使用 plantuml 若是数据库表结构的描述,允许采用ERD进行.

3 异常说明

对本方案无法解决的一些特殊情况进行说明

@fasheng
Copy link
Contributor

fasheng commented Jan 21, 2016

之前把上面的 CONTRIBUTING 看成了 CONTRIBUTORS 😭

还是用 HACKING 作为文件名吧,之前说的歧义是指 HACKING Guide 和 Contribution Guidelines 这两个文档。。。

@Match-Yang
Copy link

HACKING 参考给出的链接实效了

@fasheng
Copy link
Contributor

fasheng commented Jan 28, 2016

已经更新,记得名字用 HACKING ;)

@snyh
Copy link
Member Author

snyh commented Jan 28, 2016

.... 看来我的历史记录里面要有2个很二的Commit了... 

@fasheng fasheng changed the title 完善项目文档 完善项目下的 README/HACKING 文档 Jan 29, 2016
@fasheng fasheng closed this as completed Jul 11, 2016
This was referenced Nov 18, 2024
This was referenced Nov 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants