目录

• 1. 概述
• 2 为什么采取博文的形式提交作业
• 3. 博文规范
• 4. 代码提交

摘要：

本文介绍软件工程课程作业提交规范，解释了为什么要以博文的形式提交，怎么让博文便于他人阅读，代码怎么提交。

1. 概述

软件工程课程作业发布与提交均采用博文的形式。老师在班级博客发布作业，学生阅读博文，完成作业，并将作业以博文的形式发布在自己的博客。

如果作业涉及到源代码，在博文中只添加核心源代码，并在博文中以超链接的形式给出引用。完整源代码上传到代码托管网站，建议使用 GitHub或者https://coding.net/。

2 为什么采取博文的形式提交作业

传统提交作业的方法，将所有东西（包括源代码）放在一个word文件，可读性较差。使用博客提交作业，博文插入源代码可以高亮，便于阅读。除此之外，还有如下好处：

• 在博文以超链接的形式添加引用更加自然，也方便阅读者跳转；
• 每次作业记录自己的所思所想，好的想法值得分享，被更多人看到（比如通过搜索引擎搜索到你的文章），他人的评论也许可以完善你的想法，甚至可以交到志同道合的朋友；
• 提交word文档，会假想阅读者是老师或者助教。但写博文，会假想阅读者是网络上的任何一个人，这样会潜意识地督促自己写得更好（比如更加深入浅出）；
• 其他

3. 博文规范

对于博文的要求，归结起来是便于他人阅读，即你的想法要很容易并且高效地被阅读者理解。可以从两方面达成这个目标：

• 语言组织。想想如何深入浅出地表达自己的想法，尽量做到每一句话都有它的用途。
• 排版。想想怎么排版，方便阅读者follow你的逻辑。

我想到的一些便于他人阅读的方法：

• 提交作业时，选择添加新随笔。不要选择文章，否则班级博客上无法看到你的博文，也就无法打分。
• 博客标题格式为：“第*次作业：加上你响亮的标题”（比如“第1次作业：一个工程师成长的心路历程”），方便助教批改作业。
• 在博文的开头，写个摘要，简要说明这篇博文包含哪些内容。建议将摘要的内容，也拷贝到高级选项中的摘要（见图1），这样做的好处是，你的博客会很整洁。
• 使用章节层次，比如2, 2.1, 2.1.1，并且写好标题。
• 合理插入引用。比如引用了其他博文的部分内容，阅读者可能想读整篇文章，你给出引用，这样就方便读者了。
• 在文中需要的地方只给出核心源代码，甚至更进一步，给出一个MWE（Minimal Working Example）。

图1：博客园在随笔添加摘要

4. 代码提交

如果作业涉及到源代码，将程序在自己的机器上调试好，再上传到代码托管网站，建议使用https://coding.net/ 或者GitHub。

为每一次作业创建一个仓库（repository）。并且在博文一开始写明本次作业的项目地址（比如https://github.com/sparkandshine/complex_network）。如果在博文中引用了哪个文件，以超链接的形式在文中添加引用。

在项目的根目录创建一个名为README.md的文件，对本程序作一个简单介绍，包括但不局限于：

• 这个程序用于做什么
• 怎么运行这个程序，比如参数解释。（可以理解成给出一个用户使用手册）
• 本程序的运行环境（比如所依赖的库）

（1）怎样使用git提交代码

网上有很多手把手教程，比如：

• GitHub Help: https://help.github.com/
• http://rogerdudler.github.io/git-guide/index.zh.html
• http://www.cnblogs.com/hebau-may/p/6382743.html

（2）需要提交的应该有

• 项目的工程文件，例如Eclipse的项目文件
• 项目的源代码
• 一些必要的配置
• 单独创建一个public子目录，存放编译后的可执行程序，这不是标准的软件发布的做法，但是目前你可以先这样提交

（3）不应该提交的有：

• bin目录
• obj目录
• target目录
• .idea目录
• .settings目录
• build目录，compile后生成的文件夹
• .classpath文件
• .DS_Store目录
• .project文件
• *.iml IDE的配置文件、文件夹

可以在项目代码的根目录下创建一个.gitignore文件，把需要忽略的文件夹和文件相对路径逐行添加进去，这样git 提交的时候就会忽略这些子目录和子文件。一个.gitignore模板示例：

/target/
/.idea/
/.settings/
/build/
/.classpath
/.DS_Store/
.project
*.iml
/obj/
/bin/

注：本博文由软件工程教学小组共同完成，尤其感谢@Grey，完善了本文档。