软件构造Lab1完全指南：从代码规范到工程思维

1. 从一份实验报告说起：软件构造Lab1到底在练什么

如果你正在读软件工程或者计算机相关专业，大概率会在某个学期遇到一门叫“软件构造”的课。这门课和数据结构、算法设计不太一样，它不追求让你写出多复杂的逻辑，而是盯着一个容易被忽视的问题：你写的代码，别人能不能看懂、能不能改、能不能放心地用。Lab1作为整门课的第一次实验，往往承担着“把野路子代码习惯掰过来”的任务。

我当年第一次拿到Lab1的实验要求时，心里想的是“不就是写几个Java类吗”。真正动手之后才发现，实验的评分点根本不在于功能跑通没有，而在于你的代码结构是否清晰、注释是否到位、异常处理是否合理、测试是否覆盖了边界情况。换句话说，Lab1是在训练一种工程化的思维方式，而不是单纯的编程能力。

这篇文章适合两类人看：一类是正在做或者即将做这个实验的同学，想提前知道里面有哪些坑；另一类是对软件构造感兴趣、想了解工程化编码到底意味着什么的自学者。我会从实验的核心目标、环境搭建、代码设计、测试策略、报告撰写这几个维度，把Lab1完整拆解一遍，尽量把每一步“为什么这么做”讲清楚。

提示：不同年份、不同教学班的Lab1具体要求可能有差异，本文基于常见的实验框架展开，具体以你拿到的实验指导书为准。

2. 实验的核心目标：不是写代码，是写“能活很久”的代码

2.1 软件构造视角下的“好代码”标准

很多同学写代码的习惯是：能跑就行。变量名用a、b、c，函数写到几百行，异常直接catch住什么都不做，注释只在老师要求的时候补两句。这种代码在单人一次性任务里确实没问题，但一旦进入团队协作或者需要长期维护的场景，就会变成灾难。

Lab1的第一个核心目标，就是让你建立一套“可维护性”的判断标准。具体来说，包括以下几个维度：

• 可读性：变量名、函数名是否能自解释，代码缩进和空行是否合理，注释是否解释了“为什么”而不是“是什么”。
• 可扩展性：新增一个功能时，是需要改动大量已有代码，还是只需要增加一个新的实现类。
• 健壮性：面对非法输入、边界条件、异常情况时，程序是直接崩溃还是给出合理的错误提示。
• 可测试性：代码是否容易被单元测试覆盖，依赖关系是否清晰。

这四个维度听起来很抽象，但在Lab1里会通过具体的任务让你反复体会。比如实验通常会要求你实现一个有一定规模的功能模块，然后写测试用例去验证它。如果你在设计阶段没有考虑可测试性，后面写测试的时候就会发现根本无从下手。

2.2 从“能跑”到“好改”的思维转变

我观察过很多同学做Lab1的过程，最大的障碍不是技术难度，而是思维惯性。大家习惯了“面向过程”地堆代码，突然要求用面向对象的方式去设计，会很不适应。

举个例子：实验里可能要求你处理一组具有不同属性的对象。面向过程的写法是写一个大的函数，里面用if-else判断类型，然后分别处理。这种写法在对象类型少的时候没问题，但一旦类型增多，函数会急剧膨胀，而且每次新增类型都要修改原有代码，违反了开闭原则。

面向对象的写法是先抽象出一个基类或者接口，把公共行为定义好，然后每种类型写一个子类去实现。新增类型时只需要加一个子类，不需要动已有代码。这个转变说起来简单，但真正动手的时候，很多人还是会不自觉地写回if-else。

注意：Lab1的评分中，代码结构往往比功能完整性占更高的权重。一个功能全部实现但结构混乱的提交，得分可能远低于功能只完成80%但结构清晰的提交。

2.3 实验任务与工程能力的映射关系

Lab1的每个任务点，其实都对应着一项具体的工程能力。我整理了一个对照表，方便你理解实验设计的意图：

这张表建议你在动手之前先看一遍，做的时候对照着检查，能帮你少走很多弯路。

3. 环境搭建：那些实验指导书不会细说的事

3.1 JDK版本选择与IDE配置

Lab1通常要求用Java完成，所以第一步是配好JDK和IDE。这里有几个细节值得注意。

JDK版本方面，实验指导书一般会指定一个版本，比如JDK 8或者JDK 11。我的建议是严格按照要求的版本来，不要图新鲜装最新的。原因很简单：不同JDK版本在API和编译行为上有差异，你用JDK 17写的代码可能在评分环境里跑不起来。特别是涉及到一些集合类的默认行为、字符串处理、日期时间API的时候，版本差异会直接导致编译错误或运行结果不一致。

IDE的选择上，Eclipse和IntelliJ IDEA都可以。Eclipse的优势是轻量、启动快，很多学校的实验环境默认就是Eclipse。IDEA的优势是智能提示更强、重构功能更完善，写代码效率更高。如果你之前没用过IDEA，建议花半小时熟悉一下基本操作，后面写代码会省很多时间。

配置的时候有一个容易忽略的点：编码格式。Java源文件默认使用平台编码，Windows中文环境下可能是GBK，而实验要求通常是UTF-8。如果编码不一致，中文注释会变成乱码，严重的话会导致编译失败。在IDE的设置里把工作空间编码和文件编码都改成UTF-8，能避免很多莫名其妙的问题。

3.2 构建工具与依赖管理

Lab1一般不会涉及太复杂的依赖，但有些实验框架会要求你用Maven或者Gradle来管理项目。如果你的实验要求里提到了构建工具，那就老老实实按它的来。

Maven的核心是pom.xml文件，你需要关注几个关键配置：

<properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties>

这三行分别指定了Java编译版本和源码编码。很多同学编译报错就是因为忘了配编码，导致中文字符无法识别。

如果你用的是Gradle，对应的配置在build.gradle里：

java { sourceCompatibility = JavaVersion.VERSION_1_8 targetCompatibility = JavaVersion.VERSION_1_8 } tasks.withType(JavaCompile) { options.encoding = 'UTF-8' }

提示：如果你不确定实验是否需要构建工具，可以先不用，直接用IDE自带的编译功能。但如果你打算把代码提交到代码托管平台，建议还是配上，方便别人拉取后直接构建。

3.3 版本控制的基本操作

虽然Lab1不一定强制要求用Git，但我强烈建议你从第一次实验开始就养成用版本控制的习惯。原因很实际：实验过程中你会不断修改代码，有时候改着改着发现改错了想回退，如果没有版本控制就只能靠记忆手动改回来。

最基本的操作流程是：

1. 在项目根目录执行git init初始化仓库。
2. 创建.gitignore文件，把编译产物（如bin/、out/、target/）和IDE配置文件排除掉。
3. 每完成一个功能点就git add和git commit，提交信息写清楚做了什么。
4. 如果实验允许，可以把代码推送到远程仓库做备份。

.gitignore的一个参考内容：

bin/ out/ target/ *.class .idea/ *.iml .settings/ .classpath .project

这个习惯在后续的Lab里会越来越重要，因为项目规模会变大，没有版本控制几乎没法管理。

4. 代码设计：从需求到实现的完整思路

4.1 需求拆解与职责划分

拿到实验任务后，不要急着打开IDE写代码。先花时间把需求读透，搞清楚要做什么、输入是什么、输出是什么、有哪些约束条件。

以常见的Lab1任务为例，假设要求实现一个“图形管理系统”，支持添加不同形状、计算总面积、按条件筛选。你可以按以下步骤拆解：

第一步，识别核心概念。这里的概念有：形状、圆形、矩形、三角形、图形管理器。每个概念对应一个类。

第二步，确定类之间的关系。圆形、矩形、三角形都是形状，所以可以抽象出一个Shape基类或接口。图形管理器负责管理一组形状，它和形状之间是聚合关系。

第三步，定义每个类的职责。Shape定义公共行为（如计算面积、获取名称），子类实现具体计算逻辑。图形管理器负责增删查改和统计。

第四步，考虑扩展性。如果以后要加新的形状类型，现有代码需要改动吗？如果不需要，说明设计是合理的。

这个拆解过程看起来简单，但很多同学跳过这一步直接写代码，结果写到一半发现结构不对，又回头重构，反而更费时间。

4.2 接口与抽象类的选择逻辑

Java里接口和抽象类都可以用来定义公共行为，但它们的适用场景不同。Lab1里经常需要做这个选择，我分享一下我的判断标准。

用接口的情况：

• 需要定义一组行为规范，但不关心具体实现。
• 一个类需要实现多个不相关的行为。
• 希望保持类之间的松耦合。

用抽象类的情况：

• 多个类有共同的属性和方法实现，可以复用。
• 需要在基类里定义一些默认行为，子类可以选择性覆盖。
• 类之间有明确的继承关系。

在图形管理系统的例子里，Shape更适合用抽象类，因为所有形状都有“名称”这个属性，而且“打印信息”这个方法可以有默认实现。但如果实验要求里形状之间没有共享状态，用接口也完全可以。

注意：不要为了用设计模式而用设计模式。Lab1的评分看重的是设计是否合理，而不是用了多少种模式。一个简单的接口加几个实现类，只要职责清晰，就是好设计。

4.3 异常处理的设计原则

异常处理是Lab1里最容易失分的地方之一。很多同学的写法是这样的：

try { // 一些操作 } catch (Exception e) { // 什么都不做 }

这种写法的问题在于：一旦出错，程序不会崩溃，但也不会给出任何提示，问题被隐藏了，调试的时候根本不知道哪里出了错。

正确的做法是：

• 能处理的异常才捕获：如果你不知道该怎么处理，就让它往上抛。
• 捕获后要有动作：至少打印日志或者包装成更友好的异常再抛出。
• 不要捕获过于宽泛的异常：尽量捕获具体的异常类型，如NumberFormatException而不是Exception。
• 异常信息要有意义：包含出错的值、期望的格式等上下文信息。

一个合理的异常处理示例：

public int parseAge(String input) { try { int age = Integer.parseInt(input); if (age < 0 || age > 150) { throw new IllegalArgumentException("年龄超出合理范围: " + age); } return age; } catch (NumberFormatException e) { throw new IllegalArgumentException("年龄格式不正确: " + input, e); } }

这个例子里，异常被转换成了更具体的类型，并且保留了原始异常作为cause，方便追踪问题。

4.4 代码注释的写法与尺度

注释不是越多越好，关键是写在该写的地方。Lab1里常见的注释问题有两种：一种是不写注释，另一种是写废话注释。

废话注释的例子：

// 设置name public void setName(String name) { this.name = name; }

这种注释没有任何信息量，因为代码本身已经说清楚了。好的注释应该解释“为什么”：

// 使用防御性拷贝，避免外部修改影响内部状态 public void setTags(List<String> tags) { this.tags = new ArrayList<>(tags); }

这个注释解释了为什么要多此一举地新建一个ArrayList，而不是直接赋值。这种信息才是读者需要的。

在Lab1里，建议在以下几个位置写注释：

• 类的头部：说明这个类的职责和设计思路。
• 复杂方法的头部：说明输入、输出、可能抛出的异常。
• 关键算法或逻辑分支：解释为什么这样处理。
• 不明显的边界条件：说明为什么取这个值。

5. 测试策略：怎么证明你的代码是对的

5.1 单元测试的基本框架

Lab1通常要求用JUnit写单元测试。JUnit 4和JUnit 5的写法略有不同，但核心思想一致：为每个公开方法写测试用例，验证正常情况和异常情况下的行为。

一个典型的JUnit 4测试类结构：

import org.junit.Test; import org.junit.Before; import static org.junit.Assert.*; public class ShapeTest { private Circle circle; @Before public void setUp() { circle = new Circle(5.0); } @Test public void testArea() { assertEquals(78.54, circle.getArea(), 0.01); } @Test(expected = IllegalArgumentException.class) public void testNegativeRadius() { new Circle(-1.0); } }

@Before注解的方法会在每个测试方法执行前运行，用来准备测试数据。assertEquals的第三个参数是浮点数比较的误差范围，因为浮点运算有精度问题，不能直接用等号比较。

5.2 边界条件与异常路径的覆盖

很多同学写测试只测正常情况，比如给圆形传一个正数半径，验证面积计算正确。但真正能发现bug的往往是边界条件和异常路径。

以圆形为例，需要测试的边界包括：

• 半径为0：面积应该是0。
• 半径为负数：应该抛出异常。
• 半径非常大：验证是否会出现溢出。
• 半径为小数：验证精度是否可接受。

异常路径的测试同样重要。如果你的方法在参数非法时抛出异常，就要写测试验证它确实抛出了正确的异常类型。JUnit 4用@Test(expected = XxxException.class)，JUnit 5用assertThrows。

提示：测试方法的命名要能说明测试意图，比如testAreaWithZeroRadius比testArea2好得多。评分的时候老师会看你的测试是否覆盖了关键场景。

5.3 测试代码的质量标准

测试代码也是代码，同样需要保持整洁。几个基本要求：

• 一个测试方法只测一件事：不要把多个断言混在一个方法里，失败了不好定位。
• 测试之间相互独立：一个测试的失败不应该影响另一个测试。
• 避免在测试里写复杂逻辑：测试应该直白，如果需要复杂计算才能验证结果，说明设计可能有问题。
• 使用有意义的断言消息：assertEquals("面积计算错误", expected, actual, 0.01)比没有消息的断言更容易排查问题。

5.4 测试覆盖率的合理追求

有些实验会要求测试覆盖率达到某个百分比。我的建议是：不要为了覆盖率而写测试。覆盖率只是一个参考指标，100%的覆盖率不代表没有bug，80%的覆盖率也可能已经覆盖了所有关键路径。

优先覆盖以下内容：

• 所有公开方法的正常路径。
• 所有参数校验的异常路径。
• 所有条件分支的两个方向。
• 循环的零次、一次、多次情况。

把精力花在这些地方，比盲目追求行覆盖率更有价值。

6. 实验报告撰写：把思考过程留下来

6.1 报告结构的设计

实验报告不是代码的堆砌，而是你设计思路的记录。一份好的Lab1报告通常包含以下部分：

1. 实验目标：用自己的话复述实验要解决的问题，不要照抄指导书。
2. 设计思路：说明你如何拆解问题、如何划分模块、为什么这样设计。
3. 核心代码说明：挑选关键代码片段，解释其作用和设计意图。
4. 测试设计与结果：说明测试了哪些场景，结果如何，发现了什么问题。
5. 问题与解决：记录实验过程中遇到的困难和解决过程。
6. 总结与反思：你从这次实验中学到了什么，还有哪些不足。

其中第2部分和第5部分是拉开差距的地方。很多同学的报告只有代码和截图，缺少设计决策的记录，得分自然不高。

6.2 设计决策的记录方式

记录设计决策时，可以采用“问题-方案-理由”的结构。比如：

问题：形状的面积计算方式各不相同，如何统一处理？

方案：定义Shape抽象类，声明抽象方法getArea()，各子类实现具体计算。

理由：这样新增形状时只需添加子类，不需要修改管理器代码，符合开闭原则。

这种写法能让老师看到你的思考过程，而不是只看到最终结果。

6.3 常见报告失分点

根据我的观察，Lab1报告常见的失分点包括：

• 只贴代码不解释：报告变成代码仓库，看不出设计思路。
• 截图不清晰：运行结果截图模糊，或者只截了一部分。
• 缺少测试说明：没有说明测试了哪些场景，测试结果如何。
• 格式混乱：标题层级不清、代码没有高亮、段落没有分段。
• 抄袭痕迹明显：和别人的报告结构、措辞高度相似。

避免这些问题的方法很简单：用自己的话写，把自己的思考过程写出来。哪怕设计不完美，真实的思考也比完美的抄袭有价值。

7. 那些年我踩过的坑与总结的经验

做Lab1的过程中，我踩过不少坑，有些是技术上的，有些是习惯上的。这里挑几个有代表性的分享一下。

第一个坑是忽视编译警告。Java编译器给出的警告（比如未使用的变量、未检查的类型转换）很多人直接忽略。但有些警告背后隐藏着真正的bug，比如资源未关闭、空指针风险。我的建议是把IDE的警告级别调高，尽量让代码零警告。

第二个坑是测试写得太晚。我一开始的习惯是先写完所有功能代码，再补测试。结果发现代码结构对测试不友好，很多方法依赖外部状态，根本没法单独测试。后来改成先写接口和测试，再写实现，代码质量明显提升。这就是测试驱动开发的价值。

第三个坑是注释和代码不同步。改代码的时候忘了改注释，导致注释误导读者。后来我养成了一个习惯：每次修改方法签名或行为时，先改注释再改代码，确保两者一致。

第四个坑是提交前不检查。有一次提交后发现有个文件忘了保存，编译都通不过。从那以后，我每次提交前都会执行一次完整的编译和测试，确认没问题再提交。

关于Lab1，我最大的体会是：它训练的不是编程能力，而是工程习惯。这些习惯在后续的课程和工作中会反复被验证其价值。变量命名规范、异常处理合理、测试覆盖充分、注释清晰准确，这些看起来是小事，但积累起来就是专业和业余的分界线。

如果你正在做这个实验，我的建议是不要把它当成负担，而是当成一次刻意练习。每写一个类，问自己“这个类的职责是什么”；每写一个方法，问自己“边界条件处理了吗”；每写一行注释，问自己“这行注释解释了为什么吗”。把这些问句变成习惯，Lab1的目标就达到了。

最后分享一个实用技巧：如果你在设计中纠结用接口还是抽象类、用继承还是组合，可以先把两种方案都写出来，比较一下哪种改动更少、哪种更容易测试。实践出真知，写两遍比想半天更有效。