作业提交:博文规范
2017-09-12 16:55
113 查看
摘要:
本文介绍软件工程课程作业提交规范,解释了为什么要以博文的形式提交,怎么让博文便于他人阅读,代码怎么提交。
[TOC]
如果作业涉及到源代码,在博文中只添加核心源代码,并在博文中以超链接的形式给出引用。完整源代码上传到代码托管网站,建议使用 GitHub或者https://coding.net/。
在博文以超链接的形式添加引用更加自然,也方便阅读者跳转;
每次作业记录自己的所思所想,好的想法值得分享,被更多人看到(比如通过搜索引擎搜索到你的文章),他人的评论也许可以完善你的想法,甚至可以交到志同道合的朋友;
提交word文档,会假想阅读者是老师或者助教。但写博文,会假想阅读者是网络上的任何一个人,这样会潜意识地督促自己写得更好(比如更加深入浅出);
其他
语言组织。想想如何深入浅出地表达自己的想法,尽量做到每一句话都有它的用途。
排版。想想怎么排版,方便阅读者follow你的逻辑。
我想到的一些便于他人阅读的方法:
提交作业时,选择添加新随笔。不要选择文章,否则班级博客上无法看到你的博文,也就无法打分。
博客标题格式为:“第*次作业:加上你响亮的标题”(比如“第1次作业:一个工程师成长的心路历程”),方便助教批改作业。
在博文的开头,写个摘要,简要说明这篇博文包含哪些内容。建议将摘要的内容,也拷贝到高级选项中的摘要(见图1),这样做的好处是,你的博客会很整洁。
使用章节层次,比如
合理插入引用。比如引用了其他博文的部分内容,阅读者可能想读整篇文章,你给出引用,这样就方便读者了。
在文中需要的地方只给出核心源代码,甚至更进一步,给出一个MWE(Minimal Working Example)。
图1:博客园在随笔添加摘要
为每一次作业创建一个仓库(repository)。并且在博文一开始写明本次作业的项目地址(比如
在项目的根目录创建一个名为
这个程序用于做什么
怎么运行这个程序,比如参数解释。(可以理解成给出一个用户使用手册)
本程序的运行环境(比如所依赖的库)
(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)不应该提交的有:
可以在项目代码的根目录下创建一个
注:本博文由软件工程教学小组共同完成,尤其感谢@Grey,完善了本文档。
本文介绍软件工程课程作业提交规范,解释了为什么要以博文的形式提交,怎么让博文便于他人阅读,代码怎么提交。
[TOC]
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文件
*.imlIDE的配置文件、文件夹
可以在项目代码的根目录下创建一个
.gitignore文件,把需要忽略的文件夹和文件相对路径逐行添加进去,这样git 提交的时候就会忽略这些子目录和子文件。一个
.gitignore模板示例:
/target/ /.idea/ /.settings/ /build/ /.classpath /.DS_Store/ .project *.iml /obj/ /bin/
注:本博文由软件工程教学小组共同完成,尤其感谢@Grey,完善了本文档。
相关文章推荐
- 个人作业2——代码规范和代码复审
- hadoop1.x作业提交过程分析(源码分析第二篇) 推荐
- Jsp实现在线作业提交系统
- 作业--->利用session防止表单重复提交
- 【Hadoop代码笔记】Hadoop作业提交之客户端作业提交
- Spark jobServer搭建+提交作业执行
- 【Hadoop代码笔记】Hadoop作业提交之Child启动map任务
- Hadoop作业提交与执行源码分析
- Hadoop MapReduce作业提交与初始化过程分析
- 使用FTP在Mainframe上提交作业
- Apache Flink流作业提交流程分析
- 作业三: 是否需要有代码规范?
- 第四周作业提交
- iOS app提交审核前注意获取权限提示语句规范
- 作业三:代码规范
- 50030(jobtracker.jsp)监控不到eclipse提交的作业
- 作业20170928-1 代码规范
- 软工2017第四周作业——代码规范
- 第一次作业:读优秀博文有感
- 第一次作业:阅读优秀博文有感