北航软工结对项目

倾然丶 夕夏残阳落幕 提交于 2020-03-22 18:13:45

结对项目

项目 内容
本作业属于北航 2020 年春软件工程 博客园班级连接
所属教学班 006
本作业是本课程结对项目作业 作业要求
我在这个课程的目标是 收获团队项目开发经验,提高自己的软件开发水平
这个作业在哪个具体方面帮助我实现目标 体验结对编程
项目代码 Github 仓库

需求分析

与上一次的个人项目作业相类似,本次的任务关键在于交点的求解。至于新需求“交点绘制”,是简单扩展,实际上是将每个交点的坐标反馈到用户。

本次任务增加了两种图形:线段与射线,它们都是特殊的直线。为什么是特殊的“直线”呢?因为本质上,这两种图形都是将无限长直线进行截断而形成的。

由于这种性质,我们不难发现,整体的求解过程几乎没有改变。上一次的求解划分方法抄录如下

  • 直线与直线
    • 平行:交点个数 0
    • 同一条直线:交点个数无限
    • 相交:交点个数 1
  • 直线与圆
    • 相离:交点个数 0
    • 相切:交点个数 1
    • 相交:交点个数 2
  • 圆与圆
    • 相离:交点个数 0
    • 相切:交点个数 1
    • 相交:交点个数 2
    • 内含:交点个数 0

但是,射线与线段毕竟不是直线,因此我们需要考虑因截断带来的影响,即所求得的交点是否在图形上。而求解交点的过程,依旧是参见 Paul Bourke 先生的文章

除此以外,我们还需要考虑射线与线段之间的新的交点,即端点的重合。

根据上述分析过程,不难得到所需的实体,UML 图如下(使用 StarUML 生成)。

接口设计

考虑到我们所要编写的库需要面对的环境是未知的,即不清楚会被什么语言以什么形式调用,因此我们选择了最广泛的 C 形式。我们希望,调用语言只要能够获取变量的地址,就能顺利地调用我们的库。具体的接口如下

// 以下的 CORE_API 均是 __declspec(dllexport),声明将要在 dll 中导出
extern "C" CORE_API GraphManager * create_graph_manager();

extern "C" CORE_API int add_line(GraphManager*, char*, Type, INTTYPE, INTTYPE, INTTYPE, INTTYPE);

extern "C" CORE_API int add_circle(GraphManager*, char*, Type, INTTYPE, INTTYPE, INTTYPE);

extern "C" CORE_API void remove_graph(GraphManager*, int);

extern "C" CORE_API int calculate_intersect(GraphManager*, char*, INTTYPE);

extern "C" CORE_API int fetch_intersect(GraphManager*, char*, FLOATTYPE*, FLOATTYPE*);

extern "C" CORE_API void clear_manager(GraphManager*);

extern "C" CORE_API void dispose_graph_manager(GraphManager*);

各个接口分别的作用是:

  • 创建 GraphManager
  • 向指定的 GraphManager 添加一条线(可能是直线、线段或射线,由 Type 指定)
  • 向指定的 GraphManager 添加一个圆
  • 从指定的 GraphManager 中删除一个图形
  • 计算指定的 GraphManager 中所管理的图形的交点
  • 从指定的 GraphManager 中获取交点信息
  • 清空指定的 GraphManager
  • 销毁指定的 GraphManager

这个 GraphManager 是我们为了不暴露具体的实现,额外设计的类,通过这个类的指针来与调用方进行互动,这样就不需要调用方有任何的定义结构体的能力。

这种设计其实是对 infomation hiding 原则和 loose coupling 原则的实践,调用方不必对被调用方的实现做任何假设,被调用方也不必对调用方的实现做任何假设,两者之间的连接只有基本类型。

关于 Design by Contract,这其实是我们曾经接触过的话题。在大二的面向对象课程中,曾使用 JML(Java Modeling Language,一种用于描述程序规格的语言)对程序的行为进行描述,并使用相关的工具链自动生成测试。Contract 其实是非常实用的,它是代码无关的,可以在使用代码实现程序之前对程序进行约束,并在实现完成后生成相应的测试。Contract 曾一度作为提案加入到 C++20 标准中,但由于提出比较晚,还需要时间进行考察调研,暂时脱离 C++20。

在设计接口的核心功能时,其实我们并没有过多地考虑 Contract,因为这一步在做需求分析时已经完成,我们已经能够确认程序的每个部分应有的功能以及相应的约束,某种程度上,需求分析的结果也是一种 Contract。

异常处理

这一部分是接口设计的后续内容。

异常处理是必要的,因为我们无法假设调用方的调用方式,否则调用方与被调用方将存在一定的非必要的耦合关系。

以下面这个接口为例子

extern "C" CORE_API int add_line(GraphManager* gm, char* msg, Type type, INTTYPE x1, INTTYPE y1, INTTYPE x2, INTTYPE y2);

调用方在尝试调用这个接口之前,对内部实现没有了解,不清楚直线各个参数的限制(当然,库文档一般会提供,我们假设文档中没有注明),那么可能会错误地提供了两个相同的点,或者超过限制范围的坐标值等等,这些都是需要反馈的。

那么,问题就在于如何反馈异常。首先,不可能抛异常(尽管我们的库是使用 C++编写的,具有抛异常能力),不同的语言与环境的异常模型未必相同,调用方不一定能够完成异常的处理。我们依旧需要一个通用的做法,选择返回错误信息的长度与错误信息的指针(对于本接口,返回值即错误信息长度,msg 用于存储错误信息的指针),如果错误信息的长度为 0,意味着没有异常发生,这里同样只有基本类型的参与。

根据需求,我们设计了以下几种异常类型:

  • 直线两点重合
  • 输入参数的大小不在限定范围内
  • 圆半径为负
  • 在计算交点之前就尝试获取交点信息
  • 无交点却尝试获取交点信息
  • 输入数据中具有重合或重复的图形

对于最后一种情况,即会产生“无限多交点”的情况,我们容许它的发生,会以警告的形式反馈给用户,但是会将发生重合的图形连接成为一个图形进行计算。

单元测试

先展示覆盖情况(使用 OpenCPPCoverage 生成)

测试的框架如下

static int main_ret = 0;
static int test_count = 0;
static int test_pass = 0;

#define EXPECT_EQ_BASE(equality, expect, actual) \
    do {\
        test_count++;\
        if (equality)\
            test_pass++;\
        else {\
            std::cerr << __FILE__ << ":" << __LINE__ << ": expect: " << expect << " actual: " << actual << "\n"; \
            main_ret = 1;\
        }\
    } while(0)
#define EXPECT_EQ(expect, actual) EXPECT_EQ_BASE((expect) == (actual), expect, actual)
#define EXPECT_TRUE(actual) EXPECT_EQ_BASE((actual) != 0, "true", "false")
#define EXPECT_FALSE(actual) EXPECT_EQ_BASE((actual) == 0, "false", "true")

void gm_test()
{
    auto gm = create_graph_manager();
    ... // 测试项目
    dispose_graph_manager(gm);
}

int main()
{
    gm_test();
    printf("%d/%d (%3.2f%%) passed\n", test_pass, test_count, test_pass * 100.0 / test_count);
    return main_ret;
}

测试项目有功能性测试和异常测试。

首先是功能性测试,以测试两圆外切情况为例

clear_manager(gm);                              // 首先清空 GraghManager
add_circle(gm, nullptr, Type::circle, 0, 0, 1); // 加入一个圆,用空指针接收错误信息可以及时发现异常的发生
add_circle(gm, nullptr, Type::circle, 2, 0, 1); // 加入另一个圆
EXPECT_EQ(1, calculate_intersect(gm));          // 计算交点数并进行比较

测试数据的构造会考虑正负零以及在数据范围附近的情况(-100000, 100000),分类的依据可见需求分析。

然后是异常测试,大致如下

// 两点重合
clear_manager(gm);
EXPECT_TRUE(add_line(gm, msg, Type::line_segment, 0, 0, 0, 0) > 0);
// 超出数据范围
clear_manager(gm);
EXPECT_TRUE(add_line(gm, msg, Type::line_segment, 10000000, 0, 0, 0) > 0);
// 超出数据范围
clear_manager(gm);
EXPECT_TRUE(add_line(gm, msg, Type::line_segment, 0, 0, 0, -10000000) > 0);
// 超出数据范围
clear_manager(gm);
EXPECT_TRUE(add_circle(gm, msg, Type::circle, 0, 0, -10000000) > 0);
// 半径为负
clear_manager(gm);
EXPECT_TRUE(add_circle(gm, msg, Type::circle, 0, 0, -1000) > 0);
// 计算交点前获取交点信息
clear_manager(gm);
EXPECT_TRUE(fetch_intersect(gm, msg, &x, &y) > 0);
// 无交点获取交点信息
calculate_intersect(gm, msg, &point_num);
EXPECT_TRUE(fetch_intersect(gm, msg, &x, &y) > 0);
// 输入数据中具有重合或重复的图形
add_circle(gm, nullptr, Type::circle, 0, 0, 3);
add_circle(gm, nullptr, Type::circle, 0, 0, 3);
EXPECT_TRUE(calculate_intersect(gm, msg, &point_num) > 0);

界面模块设计

界面模块我们选取的开发框架是 WPF,开发语言为 C#。由于项目给出的界面模块需求为几何对象的文件导入、增删、绘制与交点求解,这些需求都可以通过按钮点击事件完成,故界面模块的总体设计为:上方用画板展示绘制内容,下方排布按钮进行控制。完成后的初始界面如下:

画布设计

画布设计又分为坐标网格的绘制与几何图形的绘制,下面解释二者的实现细节。

坐标轴的绘制比较简单,只需在画布中央画两条直线,其中 y 轴的两端为画布上下边界的中点,x 轴的两端为画布左右边界的中点。而坐标网格的绘制其实也只是坐标轴绘制的一个加强版,横纵线交错即为网格;坐标的绘制通过TextBlock实现。下面是展示沿 X 轴方向的坐标网格和坐标的绘制,y 轴同理翻转即可。

几何对象绘制设计

几何对象的绘制分为线绘制和圆形绘制,其中线绘制又分为无限长直线、射线和线段。

线绘制最为麻烦,因为 WPF 框架中给出的现有方法只支持绘制线段,不支持无限长直线。我们对于无限长直线和射线的实现办法为:添加边界点。边界点的求法为:令横坐标 x 为 INF_X(这里取 INF_X 为画布宽度的一半,也就是把画布放到二维坐标系的中心时的边界值),利用直线方程求出 y。需要考虑平行于坐标轴的情况,下方代码不再赘述:

// input: x1, y1, x2, y2
double A = y2 - y1, B = x1 - x2, C = x2 * y1 - x1 * y2;
double edge_x1, edge_x2, edge_y1, edge_y2;  // 1为边界起点,2为边界终点
double INFX = frame_width / 2;

if (x2 < x1)
{
    edge_x1 = INFX;
    edge_x2 = -INFX;
}
else
{
    edge_x1 = -INFX;
    edge_x2 = INFX;
}
edge_y1 = (-C - A * edge_x1) / B;
edge_y2 = (-C - A * edge_x2) / B;

之后即可根据线对象的类型进行绘制。需要注意的是,之前在二维坐标系中进行计算,最后绘制时应将点坐标转换到画布的坐标系(也就是二维坐标系沿 x 轴翻转后取第四象限)中去:

Point start;
Point end;
switch (type)
{
    case Type.infinite_line:    // 无限长直线
        start = convert_point(edge_x1, edge_y1);
        end = convert_point(edge_x2, edge_y2);
        break;
    case Type.line_segment:     // 射线
        start = convert_point(x1, y1);
        end = convert_point(edge_x2, edge_y2);
        break;
    case Type.segment: default:    // 线段
        start = convert_point(x1, y1);
        end = convert_point(x2, y2);
        break;
}

LineGeometry line = new LineGeometry();
line.StartPoint = start;
line.EndPoint = end;

Path path = new Path();
path.Stroke = Brushes.Black;
path.StrokeThickness = 1;
path.Data = line;

mainPanel.Children.Add(path);

convert_point的代码如下:

private Point convert_point(double x, double y)
{
    return new Point(x * SCALE + x_offset, -y * SCALE + y_offset);
}

圆形与坐标点的绘制可以使用 WPF 提供的EllipseGeometry(椭圆)类。二者区别只有空心实心和半径大小,下面给出坐标点的绘制方法:

// input: x, y
Point p = convert_point(x, y);
EllipseGeometry el = new EllipseGeometry();
int pointR = 2;

el.RadiusX = pointR;
el.RadiusY = pointR;
el.Center = p;

Path path = new Path();
path.Stroke = Brushes.Black;
path.StrokeThickness = 2;
path.Fill = Brushes.Black;
path.Data = el;

mainPanel.Children.Add(path);
intersections.Add(path);

按钮设计

按钮的功能设计如下:

  • Files:从文件导入几何对象的描述并绘制(不独立设置“绘制”按钮是为了更直观地展示输入的几何对象,避免用户进行重复冗余的点击操作,下面的增添/删除按钮也贯彻了这一理念)。
  • Intersect:求解现有几何对象的交点并绘制。
  • Delete:选择某一个几何对象,将其从画布上删除,并删除画布中的所有交点
  • Add:根据选择的类型及输入增添一个几何对象,并在画布上画出。
  • Clear:清空画布上所有的几何对象及交点
  • Scale+/-:放大/缩小画布的坐标系,将会删除图上所有的几何对象和交点。

下面展示这些按钮触发事件的实现细节。

按钮事件函数的写法为:

  • Files

    var dialog = new Microsoft.Win32.OpenFileDialog
    {
        Filter = ".txt|*.txt"
    };
    if (dialog.ShowDialog(this) == false) return;
    string fileName = dialog.FileName;
    
    Console.WriteLine(fileName);
    
    drawer.clearAll();      // 清除画布
    drawer.DrawXY();        // 重新绘制坐标轴
    drawer.ReadGraphFromFile(fileName);
    

    其中read_graph_from_file()方法的实现流程为:

    • 读文件第一行的数字
    • 根据数字按行读取并 parse
    • 将 parse 后获得的几何对象信息输入到core中的计算模块进行添加
    • 调用线绘制方法进行绘制

    其中还涉及若干错误判断,使用MessageBox.show()报告错误

  • Intersect

    该事件主要调用core中的计算模块,并使用core中实现的取交点函数逐一获取所有交点。

    public void calc_and_draw_intersects()
    {
        // 计算交点
        int r = NativeMethods.calculate_intersect(core_graph_manager, msg, ref n);
        if (r > 0)
        {
            MessageBox.Show(msg.ToString());
        }
    
        for (long i = 0; i < n; i++)
        {
            // 从core中取一个交点坐标
            r = NativeMethods.fetch_intersect(core_graph_manager, msg, ref x, ref y);
            if (r > 0)  // 如果有错误信息
            {
                MessageBox.Show(msg.ToString());
                break;
            }
            else
            {
                drawIntersectPoint(x, y);
            }
        }
    }
    
  • Delete

    该事件弹出新窗口(项目中为GraphsWindow),获取当前所有几何对象的信息,并使用ListBox陈列,用户确认选择后分别删除其在ListBox中的描述、画布中的图形以及在core中的对象,并删除所有交点。

    画布中删除某一图形的逻辑如下:

    // input: graph id
    // remove graoh on Canvas
    mainPanel.Children.Remove(graphs[id]);
    
    // remove info
    graphs.Remove(graphs[id]);
    
    // remove points on graph
    Path[] points = pointsOnGraph[id];
    foreach (Path point in points)
    {
        mainPanel.Children.Remove(point);
    }
    pointsOnGraph.Remove(points);
    
    // remove intersections(all)
    foreach (Path intersect in intersections)
    {
        mainPanel.Children.Remove(intersect);
    }
    intersections.Clear();
    
    // remove data in core
    remove_graph(core_graph_manager, id);
    
  • Add

    弹出新窗口进行几何对象的添加。实现方法是使用ComboBox实现下拉栏选择四种几何对象类型的其中一个,并根据类型的不同给出不同数量的参数输入框(TextBox)。提交输入时进行正确性检测。最后将正确的输入整合为一行,利用按行处理文件输入的方法进行添加处理。

    string wrongMsg = "";
    verify_TextInput(tbox1, tblock1, ref wrongMsg);
    verify_TextInput(tbox2, tblock2, ref wrongMsg);
    verify_TextInput(tbox3, tblock3, ref wrongMsg);
    if (combo.SelectedIndex != (int)ComboItem.C)    // 圆形没有第四个参数输入框,只有x, y, r
    {
        verify_TextInput(tbox4, tblock4, ref wrongMsg);
    }
    
    if (wrongMsg.Length != 0)
    {
        MessageBox.Show(wrongMsg);  // 输入栏的错误提醒
    }
    else
    {
        string info = combo.Text + " " + tbox1.Text + " " + tbox2.Text + " " + tbox3.Text;
        if (combo.SelectedIndex != (int)ComboItem.C)
        {
            info += " " + tbox4.Text;
        }
        try
        {
            drawer.AddGraphFromLine(info);  // 添加该行对应的几何对象信息
        }
        catch (FormatException)
        {
            MessageBox.Show("Wrong Format!");   // 在执行添加逻辑时的错误报告
        }
    }
    
  • Clear

    该事件包括清除画布内容、几何对象所有信息,并重新绘画坐标网格。清除的细节如下:

    mainPanel.Children.Clear();     // 清除画布内容
    graphs.Clear();                 // 清除几何对象绘制信息
    intersections.Clear();          // 清除交点绘制信息
    pointsOnGraph.Clear();          // 清除几何对象上的点(起点、终点、圆心)的绘制信息
    graphsInfo.Clear();             // 清除用于生成ListBox的几何对象信息
    core_graph_manager = IntPtr.Zero;   // 清除core中的manager
    
  • Scale + / -

    该事件由调整画布尺寸参数SCALE实现。坐标网格绘制中,在绘制垂直 x 轴的坐标网格的循环语句中,网格密度是根据SCALE来调整的,由此实现画布的尺寸增减:

    for (int i = SCALE; i < frame_width / 2; i+=SCALE)
    

    在实现中,用户每点击一次按钮 Scale+/-,首先清除画布,SCALE增加/减少5,并进行设定边界,避免无限放大,然后再重新绘制坐标轴。

    如下是实现的大致逻辑

    if (SCALE >= 100)
    {
        MessageBox.Show("Reach Max Scale", "Note");
        return;
    }
    clear_all();
    SCALE += 5;
    drawXY();
    

界面模块与计算模块的对接

计算模块生成动态链接库提供,由于界面模块使用的是 WPF 框架及 C# 进行开发,可以通过DLLImport语句可以导入 dll 中的接口进行使用。

在界面模块中导入接口函数的语句如下:

[DllImport("core.dll")]
internal static extern IntPtr create_graph_manager();

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi, BestFitMapping = false, ThrowOnUnmappableChar = true)]
internal static extern int add_line(IntPtr gm, StringBuilder msg, int type, long x1, long y1, long x2, long y2);

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi, BestFitMapping = false, ThrowOnUnmappableChar = true)]
internal static extern int add_circle(IntPtr gm, StringBuilder msg, int type, long x, long y, long r);

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi, BestFitMapping = false, ThrowOnUnmappableChar = true)]
internal static extern int calculate_intersect(IntPtr gm, StringBuilder msg, ref long res);

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi, BestFitMapping = false, ThrowOnUnmappableChar = true)]
internal static extern int fetch_intersect(IntPtr gm, StringBuilder msg, ref double x, ref double y);

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl)]
internal static extern void remove_graph(IntPtr gm, long id);

[DllImport("core.dll", CallingConvention = CallingConvention.Cdecl)]
internal static extern void dispose_graph_manager(IntPtr gm);

为了达到松耦合的条件,界面模块中不涉及计算模块的类操作。通过 GraphManager 指针对接各个接口。初始时需创建新的 GraphManager 指针:

IntPtr graph_manager = create_graph_manager();

之后在添加一条直线,根据输入得到的类型及坐标,即可如下添加一条直线:

add_Line(graph_manager, msg, type, x1, y1, x2, y2);

其中 msg 用于获取计算模块的错误信息,通过MessageBox报告给用户。

实现的功能如下:

  • 从文件中读取几何图形信息并画出(Files 按钮)
  • 求交点并画出(Intersect 按钮)
  • 删除一个几何图形(Delete 按钮)

  • 增添一个几何图形(Add 按钮)

  • 清空画布(Clear 按钮)

  • 画布尺寸增减(将会删除图形)
    • Scale+按钮
    • Scale-按钮

代码质量分析

截图如下

结对过程

由于疫情,我们采用 Live Share 和语音聊天的方式来进行结对编程。说实话,效果一般,我们甚至还不太了解对方。但是效果还是有的,譬如说,描述坐标的变量都是 x,y 之类的,我常因为不够细心而弄错变量名,如果是我单独编程,这些问题很可能会推迟到单元测试时才会被发现,幸亏我的队友比较细心,堪比 clang-tidy,及时提醒我修正。

这其实就是结对编程的一个好处,两双眼睛同时 review 代码。同时,由于有其他人的介入,会迫使自己尽可能地写出富有意义的代码,也就是说,能让队友轻易地看懂代码的意图并了解执行的流程。

这次的任务有图形化编程的需求,这是我不太擅长的,而队友在这方面对我有很大的帮助,在看代码的时候也大致地了解了 WPF 开发的方式。

PSP 表格

PSP2.1 Personal Software Process Stages 预估耗时(分钟) 实际耗时(分钟)
Planning 计划
· Estimate · 估计这个任务需要多少时间 5 15
Development 开发
· Analysis · 需求分析 (包括学习新技术) 60 120
· Design Spec · 生成设计文档 30 30
· Design Review · 设计复审 (和同事审核设计文档) 30 30
· Coding Standard · 代码规范 (为目前的开发制定合适的规范) 0 0
· Design · 具体设计 30 90
· Coding · 具体编码 60 90
· Code Review · 代码复审 30 60
· Test · 测试(自我测试,修改代码,提交修改) 60 90
Reporting 报告
· Test Report · 测试报告 10 10
· Size Measurement · 计算工作量 10 10
· Postmortem & Process Improvement Plan · 事后总结, 并提出过程改进计划 30 30
合计 355 575
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!