软件工程结对项目博客作业

项目 内容
本作业属于北航 2020 年春软件工程 博客园班级连接
本作业是本课程个人项目作业 结对项目作业
我在这个课程的目标是 提高软件开发能力、团队协作能力
这个作业在哪个具体方面帮助我实现目标 增加协作开发经验
项目代码 https://github.com/btapple/Intersect

一、需求分析与UML图

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

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

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

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

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

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

UML图如下:

二、接口设计与实现

Information Hiding,Interface Design,Loose Coupling

  我们本次的接口设计依照了Imformation Hiding(信息隐藏)原则与Loose Coupling(松耦合)原则,体现在通过一个特定的管理器指针与调用方互动,不会涉及类成员的修改,保证信息的隐藏;通信的参数都是基本类型参数,双方不必为各自的实现考虑,保证松耦合特性。

Design by Contract,Code by Contract

  Design by Contract,契约式设计,其强调前置条件、后置条件与不变式,是一种形式约束。DbC的优点正如它的初衷,能够保证程序正确,它是一种形式逻辑上的正确,而不是测试之后得出的正确率,所以非常可靠,但其缺点是使得代码臃肿、工作量增大。OO课程中有一个单元练习的JML体现的便是这种思想,当程序复杂时带来的约束编写的工作量也会成倍增加。Code By Contract也是同样的道理,按照约束编写能够保证可靠,但是强行依照断言编写程序会造成代码的冗余和复杂,且如果约束复杂,也会增加理解交流的成本,降低效率。

本次结对项目中,我们没有过多使用Contract这种理念,而是在需求分析时确定应有的约束,保证项目“敏捷”地进行下去。

接口实现

  考虑到我们所要编写的库需要面对的环境是未知的,即不清楚会被什么语言以什么形式调用,因此我们选择了最广泛的 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*);

各个接口分别的作用是:

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

性能分析与改进

性能分析结果:

其中消耗最大的函数是求交点函数calculate_intersect

  由于改进的切入点只有交点计算的算法改进,而计算的算法没有稳定改进办法,所以性能改进上处理不多。

三、异常处理

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

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

以下面这个接口为例子

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);

五、UI设计及与计算模块的对接

  界面模块我们选取的开发框架是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+/-:放大/缩小画布的坐标系,将会删除图上所有的几何对象和交点。

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

  按钮事件函数的写法为:

private void Button_click(object sender, RoutedEventArgs e)
{
    // xxx
}
  1. 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()方法的实现流程为:

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

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

  2. 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);
            }
        }
    }
    
  3. 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);
    
  4. 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!");   // 在执行添加逻辑时的错误报告
        }
    }
    
  5. Clear

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

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

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

11.界面模块与计算模块的对接。详细地描述 UI 模块的设计与两个模块的对接,并在博客中截图实现的功能。(4')

  计算模块生成动态链接库提供,由于界面模块使用的是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);

  为了达到松耦合的条件,界面模块中不涉及计算模块的类操作。通过IntPtr型的计算模块管理器对接各个接口。如初始时创建新的计算模块管理器:

IntPtr graph_manager = create_graph_manager();

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

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

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

实现的功能如下:

  1. 从文件中读取几何图形信息并画出(Files按钮)

  2. 求交点并画出(Intersect按钮)
  3. 删除一个几何图形(Delete按钮)

    2020-03-21-22-12-26.png
  4. 增添一个几何图形(Add按钮)

  5. 清空画布(Clear按钮)

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

七、结对编程过程

  我们采用的结对编程方式是Live Share+语音,其中存在的问题,一方面是live share本身的不稳定,对方的修改可能经过一定延迟才能看到;另一方面是,互相不太了解可能产生一定的阻碍。但结对编程也带来一定好处,比如能够学习到队友比较良好的代码规范和新颖的编码技巧,并且有人一起review也减少了错误的产生,遇到比较纠结的问题时也能够通过沟通找到答案。队友在编码规范、设计能力以及项目管理等方面都很优秀,在交流中也能够精准地给出解答的方向,有时我可能会跟不上。我在此次项目中也用心、勤奋、认真地参与其中,但是对于代码规范、版本管理等细节问题还存在缺陷。

讨论图形界面时:

讨论模块对接时:

八、PSP表格

PSP2.1 Personal Software Process Stages 预估耗时(分钟) 实际耗时(分钟)
Planning 计划
· Estimate 估计这个任务需要多少时间 30 30
Development 开发
· Analysis 需求分析 (包括学习新技术) 120 240
· Design Spec 生成设计文档 30 30
· Design Review 设计复审 (和同事审核设计文档) 20 20
· Coding Standard 代码规范 (为目前的开发制定合适的规范) 10 5
· Design 具体设计 60 60
· Coding 具体编码 120 240
· Code Review 代码复审 30 60
· Test 测试(自我测试,修改代码,提交修改) 60 120
Reporting 报告
· Test Report 测试报告 10 10
· Size Measurement 计算工作量 10 10
· Postmortem & Process Improvement Plan 事后总结, 并提出过程改进计划 60 30
合计 560 855
posted @ 2020-03-22 23:13  kingkongk  阅读(257)  评论(3编辑  收藏  举报