至需求分析阶段的软工总结

认知上的收获

1. 知道了写文档的重要性

       由于之前写的东西都是比较小的项目，而且基本不需要多人协作开发，所以没有养成写注释和文档的习惯。但是自从软工的第一节课起就意识到了如今软件开发行业中文档的重要性，由于代码量大、开发人员多，规范地写注释就尤为重要。我们从前也是先写代码，写完比对着代码再写需求文档，这很容易导致开发出的功能不是用户真正需要的功能。而且每部分代码的功能可能会有一些重叠，项目的结构也不会很清晰。
       而且，文档最好写版本号，这样才能够看出我们的整个思想变化，增加了哪些东西，又删除了哪些东西，以及增删背后的原因。
       本次课程也写了不少的文档，发现了自己的语言表达能力存在很大不足。有时写完一句话，自己再读一遍都理解不了，通过前面的课程对自己的表达能力也是一种锻炼。

2. 需求的真正意义

       需求不仅仅是给用户一个他没有的东西，而是能告诉他这个新东西能够给予他怎样的帮助，能够告诉用户how to do。这个对用户才是有意义的，因为即使我们有很多的东西展示给用户，但是用户自己都不知道能拿它来做什么，这需要我们进行挖掘、引导。
       举例来说，我们一开始认为生成一个类图对用户来说很有意义，但是我们没能讲清楚用户能用类图去做什么，这个类图能给用户带来什么样的帮助，能告诉用户how to do。这是我们所要去思考的地方。此外，按照我们讨论的想从一段代码中获取知识，最直观地当然是阅读注释，但是用户拿到这些注释之后又能做什么，对他有什么帮助，这都需要我们来把这个故事将清楚、讲明白。

3. 领域分析很重要

       所谓领域分析，我认为就是看看这一领域的其他人在做什么，这往往比自己拍脑袋想方案要有效得多。我们需要看看这一领域的前人做了哪些工作，以及其存在的不足，他们方法存在不足的原因是什么，这往往就是我们可以做改进的地方。
       举例而言，我们针对此次项目调研了一些Java代码的分析软件，发现他们的功能大同小异。(1)代码格式的检查和标准化(2)检查代码中的一些bug。很少有软件能够帮助用户去理解这段代码。而软件understand就有一些独特的功能，我们的很多用例也是参考了它的软件功能，参考已有的成熟的软件，能帮助我们少走很多弯路。也能让我们对最终的成品的展现形式在心中有一个轮廓。
       结合每周的组会感受更深，这就相当于是国内外研究现状，看一看别人在做些什么，存在有哪些gap，自己的想法是不是已经有前人实现了，他实现的过程与自己的想法有哪些异同，博观而约取，厚积方薄发。

4. 我们对这个项目理解的偏差

       我们项目是有从Java代码中提取知识。我们的理解是能帮助用户去迅速、准确地去理解代码，从而能知道这段代码在做些什么。而且输入仅仅是一份代码，我们想能帮助用户生成类图，获取代码中的结构性的知识。还可以生成一个数据切面，追踪代码中某个变量的知识。
       在看完另一组的同学讲解以及老师的点评后，也意识到了我们的问题。一方面，我们只考虑了单个文件，而且我们更多的是想帮助用户去理解代码，而没有能去帮用户去how to do。可能项目需要的是输入一堆的同类型的训练集代码，然后自动生成一个好的样例，能够告诉用户怎么做是好的，怎么写代码是规范的。用户的代码存在有哪些问题，他应该how to do来改进自己的代码，让自己的代码更规范，有点像是一个机器学习的问题，输入大量的数据集，至于label可以取平均，降低用户输入代码的损失值。

5. 我们对这个项目的重新理解

       课后，老师给我们的建议是可以教一些新手用户如何正确、规范地使用一些类库。因为有些类库的调用需要一些依赖，或者需要使用一些assert断言来确保其正确运行。而且数据集可以从GitHub上找，然后针对几个类库写成一个帮助文档，帮助用户在使用某个类库是的一些注意点和相互依赖，可以在用户输入时完成自动提醒或者补全。我们当时觉得这个用例很有用，然后课后也进行了调研了探索。
       其实，一开始听到老师的这个想法，我立马就想到了当时初学python进行机器学习时的窘境。一方面，看国外老师的课总是喜欢用assertion断言去判断矩阵或是向量类型是否和预期一致，并且广泛地使用try catch语句来捕获异常，使代码能够顺利地执行下去，初学时感觉有点画蛇添足，到后来自己上手写代码时才意识到这些代码的重要性，这种不成文的规定可以很大程度上帮助我们的代码更健壮，更容易定位出bug。另一方面，python2和python3之间的版本问题也很让人头疼，有的函数是python2中和python3中都具有的，但是函数的参数类型又不同，这类问题引发的bug是很难发现的。所以，生成这样的一个帮助文档，能够在用户输入时自动帮用户补全依赖，提醒用户需要对数据类型、数据维度进行断言是有必要的。
       但是，经过课下的调研和讨论，以及在GitHub上阅读Java源码发现，在Java中，只有那些类似于Spring这种框架的源代码中，为了方便用户使用时测试，广泛使用了assert语句。除此之外的项目，基本都没有assert语句，我们考虑原因是这些语句是在测试时有用，而作者在发布自己的项目时，把这些语句都处理掉了。此外，针对类库的依赖管理，我们发现在idea中只要使用了maven项目，它能够自动地帮助我们添加有依赖关系的类库，所以，类似的需求已经实现了。
       我们经过进一步的讨论，结合当初使用python的经历，打算做这么一个用例。比如，我们在使用python的画图工具包时，作为一名新手，可能并不知道绘制散点图的函数已经被python封装好了，而又自己去造了个轮子。在使用Java parser时，我想获取代码中的全部的注释，而且要分成三种类型的注释，一开始是以字符串正则化匹配的方式去做，最后虽然实现了但是代码比较丑，最后发现Java parser库中已经封装好了这个函数，可以自动地获取代码中的所有注释。 这是我们可以去挖掘的地方，类库中可能已经封装好了一些函数和功能，可以自动实现我们的需求，但是我们并不知道。我们打算基于此，从GitHub上下载一些类似功能的项目代码，看实现同一个功能，star数高的项目导入了哪些类库，有没有哪些类库的组合出现的频率特别高，然后我们可以按照使用频率生成一个文档，如果用户想要实现这个功能，可以看哪些已有的函数可以帮助用户。

技术上的收获

1. 画UML图的规范

       以前画的UML图大多讲究神似，并没有去细抠其中的细节。这门课老师带我们很仔细地梳理了每幅图的细节。比如在用例图时，用户一定要写具体，不能仅仅写一个软件使用者。而且同一个用户可能会以不同的身份来使用软件，比如可能在某门课上是学生，在另一门课上就是助教，所以不同用户的用例要区分开来。然后学习使用了starUML来绘制各种UML图，比如用例图、时序图、状态图、类图等。还学习了RUCM的使用规范，各种前置条件和后置条件是我们应该注意的
       其实，画这些图并不耽误时间，反而是帮助我们理清整个项目的规范，并方便我们与用户相交流，用户看到这些天可能很快就理解了我们要表达的意思，一幅图胜过千言万语。

2. 学习使用了Maven的包管理机制

       假设你的项目依赖于一个库，而这个库又依赖于其他库。你不必自己去找出所有这些依赖，你只需要加上你直接依赖的库，Maven会隐式的把这些库间接依赖的库也加入到你的项目中。这个特性是靠解析从远程仓库中获取的依赖库的项目文件实现的。一般的，这些项目的所有依赖都会加入到项目中，或者从父项目继承，或者通过传递性依赖。这使得我们不需要为配置jar包而花费太多的精力，能够更好地专注于我们的项目本身。

3. 学习了Java parser的使用

       在学习这个类库的过程中，最大的收获就是学会了看文档。因为这个类库网上的教程比较少，只有一个英文版的书，或者说是这个类库的使用文档。体验了一下从头阅读官方文档的经历，发现其内容可读性还是比较强的，举出的一些范例也容易让人理解，以后使用一个库还是要读官方的文档才更完整。