作业提交:博文规范

摘要:

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

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提交代码 **

网上有很多手把手教程,比如:

(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,完善了本文档。

posted @ 2017-09-12 16:55  SparkAndShine  阅读(795)  评论(0编辑  收藏  举报