。

好的项目管理可以让实验进行得更加顺利。

本篇博客以一次项目实践为例#xff0c;介绍项目管理的方法#xff0c;以及可能遇到的问题#xff0c;并提供一些可行的解决方案。

项目管理工具开始第一步版本管理十分关键如何进行版本管理创建分支进行改动添加改动与上传分支带来的新问题常用的git使用命令

一些技巧让项目管理更简单项目结构构建Commit规范文档与注释

项目管理工具

项目管理困难的主要原因在于项目并非一个人构建的。

许多人同时写代码就容易出现A改了代码的同时B也改了代码二人改了同一块代码导致项目版本出现分歧的情况。

这个时候采用一个好用的项目管理工具则可以很好地解决版本冲突的情况。

Github则是一款以解决版本冲突为目标的项目管理工具该工具跨平台皆可使用并且简单易用因而成为广大程序员经常使用的项目管理工具。

本篇博客也就以此为工具展开对项目管理方法的经验介绍。

开始第一步

在注册完github账号之后你就可以开始项目管理了。

一般而言项目开始之初我们并没有一个程序项目因而我们需要先构建一个程序项目。

进入个人主页后可以在左侧个人拥有的项目库Repositories中找到新建New的按钮点击进去后会看到这样的画面。

新建一个项目之前需要先给项目起一个名字并填在Repository

name那里在Description那里可以填写对项目的介绍ps:

对项目的理解越深刻就可以用越简短的话介绍清楚这个项目到底要做什么。

写Description有助于后续进行比对并检查是否按照计划完成项目同时还可以选择该项目是否公众可见Public

Private在初始化的时候可以选择添加一个README文件ps:

建议初始化的时候就带上README文件可以在里面写一些需要项目参与者提前知道的先验知识。

push的时候是否需要忽略一些文件ps:每次进行实验都会产生许多中间文件如果都把它们git

push到repo里显然会浪费很多网络资源不利于项目开发license这个功能限制了他人对你开源代码库的程度不同license有不同的规则具体请见官方文档ps:

这个不需要在最开始就决定下来初始化一个项目的时候并不一定要确认此项不过为了后期开源代码能得到更多的关注可以随着项目进展再思考license如何选择。

建好一个代码项目应该会有一个这样的结果。

可以发现初始化README里面的内容就是我们最开始在Description栏里写的东西。

个人认为这个界面十分简洁美观github为项目开发提供的功能其实都已经集成在这一个界面上了。

菜单栏里可以看到有以下功能

Code:

这里类似于一个论坛项目参与者可以在这里提出问题其他参与者可以在这里进行讨论与解答问题ps:

项目进行的过程中总会遇到许多奇奇怪怪的问题这些问题大家共同商量出一个结果会比一个人自己闷头解决更靠谱一些这里可以帮助项目参与者达成共识可以有效提升项目的质量。

Pull

Request:

把其他分支上的代码拉到master分支上并进行版本的融合。

每个项目参与者会提供一部分功能代码这些代码规范的写法是在不同的分支上在各自分支上测试无误后再由管理者将其merge到master主分支上。

这一过程被称为pull

request其功能实现则可以在这个界面里实现。

Action:

repo列举在这里方便后来的项目参与者了解情况。

Wiki:对与项目更加详细的介绍好多东西无法在项目的注释里、README文档里讲清楚这部分信息可以都放在Wiki里进行详细介绍。

(ps:

文档管理做的越好项目质量越高但是这部分在我看了众多项目后发现得到的关注并不是很充足。

Security:

以上就是在项目创建之初我们要在远端也就是网站上进行的操作下面我们要将远端的repo与本地进行联系。

本地打开终端并输入指令git

[url]就可以从远端拉取刚刚初始化的项目代码从而使得本地与远端形成一个联系。

connection这种错一般错因在于本地机器的网络太过拉胯重启网络服务、重启机器、更改网络设置等一些操作往往可以解决ps:不过有时候就算真的这么处理了网络该连不上还是连不上我实验室机器的网络太过拉胯一把辛酸泪没有权限这要在本地设置ssh

key

https://github.com/Doris404/How2Code.git

然后就可以看到本地机器就有一个名为How2Code的文件夹里面含有一个README文档和远端的设定一样。

版本管理十分关键

Github解决的最核心的问题就是版本管理。

我们先来了解一下这个问题究竟有多复杂。

我将用一个例子来解释此问题的复杂程度。

一个三人团队要构建项目实现网上订餐功能三人在项目初始阶段约定一人实现一个功能并且初步商定的功能包括查询可点餐馆及可点菜品、下单与付款、评价与点评、纠纷处理等。

A作为项目主要负责人实现了下单与付款这个最复杂的功能B实现查询可点餐馆及可点菜品C实现评价与点评、纠纷处理这两个功能。

划分功能时大家一致认为这些代码互相独立性比较强所以三人分别在不同的机器上各自实现各自代码即可以做到版本管理。

然而在项目进行过程中出现了意想不到的情况。

A下单与付款的功能实现依赖于B显示出来的界面。

因此B最初实现的界面一旦发生改动则A的代码实现也要跟着变更。

在项目进行过程中则出现了以下情况

基于初始界面进行功能实现但于此同时B改动了一些初始界面并形成了一个新版界面A

B都上传代码此时A的代码不能在新版界面上测试通过只能在初始界面上通过但由于缺乏版本管理工具此时的代码无法通过并且我们遗失了初始界面。

Github提供了分支用于解决这个问题同样是上述情况如果我们使用branch则是另一番景象

如何进行版本管理

Github提供了branch功能可以用于版本管理这一部分我将介绍如何使用branch进行版本管理。

在本地终端进入项目文件夹输入git

使用branch进行版本管理的第一步就是创建新的分支运行git

branch

此时你已经转到这个新的分支上了就可以在这个新的分支上进行项目开发。

例如我改动了README文档添加了一些文本。

git

name]则可以将对指定文档的改动添加到改动之中如果在添加之后后悔了可以使用git

restore

add操作。

执行结束后你会发现刚才提交到改动中的改动被移除改动。

另一个git

restore将撤销你在文件中做出的改动执行结束后在文档中的改动将消失。

添加改动与上传

可以发现new_branch比master领先1个commit我们可以对new_branch的改动进行比较并决定是否merge到master分支。

点击Compare

pull

创建成功后其他参与者可以提交comment来发表对改动的建议。

更多的改动。

只要该分支上的改动没merge到master在此之前该分支上的所有改动都会集成到之前提交到pull

and

merge方案建议从前2个方案中进行选择。

前两个方案本质都是将改动以merge的形式加到master中区别在于选Create

merge

合并成一次commit。

考虑到简洁性建议选择Squash进行融合。

Rebase这个方法是三个方法中最为简洁的一种它将以线性来融合改动这同时也带来了风险。

例如如果new_branch改动和master改动出现冲突则可能出现改动覆盖的情况这意味着有一支的改动因为代码融合消失了。

因而不建议初学者使用这个融合方式。

merge得到通过后可以在master分支上看到之前的2次commit融合成1次commit提交到master分支上并且commit

分支提供了一个版本融合的方案但是总会有一些菜鸟在初次使用的时候不太熟练然后误把改动添加到master分支上我们如何保护master分支呢

Github提供一些规则来实现对主要分支的保护点击Protect

this

branch则可以添加规则来约束对master分支的改动ps:这些改动也可以在setting-Branches里进行。

添加的规则种类繁多包括每个分支的起名规则分支提交的约束等等。

request至少1次ps其他的选项可以根据个人需求进行勾选以及分支要符合标准的命名规则name_file

git

master分支代码就是最权威的改动的时候一定要基于master分支另开一个分支然后再在这个新开的分支上改动代码将改动push到这个新分支上然后将此分支merge到master分支上。

一些技巧让项目管理更简单

除了上述基于Github功能的项目管理我们也可以发动主观能动性来使得项目管理更加顺滑。

项目结构构建

在项目创建之初就应该对项目有一个明确的定位这个项目到底实现什么功能具体如何构建项目代码结构才能有利于后续的代码书写都是在项目之初有明确的定位的。

这件事情非常重要

至于如何获得明确的定位是超出本篇博客的内容ps:以我浅显的经验明确的定位并不是一次讨论就能决定的需要需求方和实现方多交流沟通确定。

Commit规范

info是要做到提示参与者这次提交具体进行了哪些改动的功能对于一个不了解情况的人而言其能阅读的文本数量实在有限因此需要提交者用最短的话描述出代码改动的核心。

建议项目之初就总结一下commit

type

train.py表示这次改动添加了train.py文件实现了train的功能。

文档与注释

文档和注释对项目实现十分重要是所有程序员的共识然而现实却是大家写文档和注释的意愿并不强烈。

一方面是因为代码书写占据了大部分程序员的大部分时间结束了一天辛劳工作的程序员实在没用动力去完成文档注释的书写另一方面文档与注释的确让项目实现变得更加简单易行但是写文档的好处主要是体现在除去文档书写者的所有人身上除非所有人都写文档和注释否则文档和注释的坚持者将遗憾地发现自己做了最多的工作而受益却是别人的。

基于上述原因文档与注释的书写情况总是不容乐观。

这篇博客不想对不写文档与注释的人进行道德上的谴责毕竟偷懒是人之常情。

本篇博客希望提供一个写文档的思路来减少善良的程序员在写文档与注释时所承担的时间开销

如何写文档才能提升写文档的效率呢我的经验是先确定文档的结构通过子标题的形式来将文档结构简明地总结出来然后填充每个子标题的具体内容。

这样做有一个好处可以极大地调动其他参与者的文档书写积极性。

例如对于网上订餐项目三人实现4个功能包括查询可点餐馆及可点菜品、下单与付款、评价与点评、纠纷处理。

A作为项目管理者对于这个项目的结构有个非常明确的认识至少要比B和C这两个参与者明确因而它非常清楚本项目的代码包含从数据库获取信息模块显示信息模块交易模块评价和售后模块。

因而项目的文档结构也应符合项目代码结构对这些模块进行各自的介绍。

对代码介绍的文档中则应包含这4个子标题并且对这些模块的具体实现进行展开解释。

代码实现上A对显示信息模块等非主写模块并不了解因此他会将这部分文档书写交给给自负责的人。

上述介绍只是写文档的最基本介绍更深入的技巧建议读者阅读一些提升写作能力的工具书。

好消息是文档的书写不止有手工书写这一种方法ps这好像是废话一些项目文档生成工具可以帮助我们从注释生成文档。

对于python代码而言可以使用Sphinx包来轻松实现项目注释文档生成。

具体使用参考博客。

注释对于我们理解函数功能有极大的作用在写注释时可以参考一些优秀项目的注释书写规范这里给出一个实例供读者参考。

class

mo***r_name,gender,config):try:self.name

config[fa***r_name]except:self.fa***r_name

fa***r_nametry:self.mo***r_name

config[mo***r_name]except:self.mo***r_name

config[gender]except:self.gender

configexcept:pass总结