源代码管理规范（SVN篇）-基本规范

文章说明了八项基本规范；

SVN使用规范.png

八项基本规范

• 如果代码没放在源代码管理软件里，等于它不存在
• 要早提交，常提交，并且不要觉得麻烦
• 提交前要检查你更改了什么
• 写提交信息时一定要认真
• 你必须自己提交你的更改内容——不能委托他人
• 编译生成的文件不要放进源代码管理软件里
• 不要上传你自己的用户设置
• 附属文件也要集成在一起

摘要：源代码管理软件是我们工作的必备工具，是许多开发团队的血液。那为什么我们都会对它有所误解呢？为什么都很难理解版本控制系统的核心价值和基本原理呢？

• 1、如果代码没放在源代码管理软件里，等于它不存在

每天重复读这句话——“使用源代码管理软件是唯一的有效措施”。除非你在工作时使用项目的源代码管理库来控制代码版本——否则代码等于没有存在过。
显然你曾发觉在你的本地机器上运行良好的代码在其他人那里运行的效果并不理想。是不是？他们不能获取你的最新版本，他们没法去归并代码文件，你没有正确地部署它（参考you're deploying it wrong）而且如果你的SSD硬盘坏了的话你将永远地失去你的劳动成果。
只要你保持这个心态——代码只有提交后才是真的安全，才是其他良好编程习惯的保障。你可以把你的任务划分成许多很小的单元以便你逐一提交。你需要频繁地这么做。你就不必担心你的硬件会不会出棘手问题。
不过更重要的意义是（至少对于你的团队领导来说），通过源代码管理软件可以看到你做了什么。使用图表并列出项目清单是个好方法，不过怎么知道他们实际上在做些什么？而使用源代码管理软件进行工作就能看得一清二楚了。

• 2、 要早提交，常提交，并且不要觉得麻烦

关于前面那点，避免“幻影代码”（就是只能在你的机器上看到的代码）的唯一方法是经常提交你的任务并且不要觉得麻烦。它可以解决你的问题，不过这样做也会对你的工作产生其他的影响：

• 1. 每个提交的修订都会为你提供一个还原点。如果你完全把代码搞砸了（没骗你，我们都这么做过），你是希望恢复到一个小时前的工作还是一周前的工作？
• 2. 归并文件时会出现的危险会随着时间不断增加。归并文件一直很麻烦。如果你不是每天都保持提交代码，某一天你会突然发现你和其他人的更改内容会有50多个冲突。你不会为此感到高兴的。
• 3. 它促使你把任务分离成分散的单元。通常人们都是快完成的时候才提交的，因为他们想把代码做成一个完整的逻辑单元模块。不过庞大的任务不可避免地要分离出较小的分散功能，而频繁地提交它们会使你更了解它们，你可以一个个地构建并提交。

如果你做到这些，你的提交历史不可避免地开始类似于一种半规律的样式，里面每个工作日都是在提交任务。当然不总是这样，也有停下来重构或测试，或者其他合理的活动也会中断标准的开发周期。

然而，当我在看一个独立的——尤其是完整的项目时，每当发现我们在一个标准的开发周期里，有一天或几天什么都没有做，我便会非常担忧。我之所以担忧 是因为这意味着什么地方出问题了。一般不是有人正在想方设法要把问题搞定的话，就是因为卡在某个问题上而导致项目完全没有进度。无论到底是什么情况，源代 码管理软件都会告诉你出现问题了。

• 3、提交前要检查你更改了什么

往源代码管理软件里提交代码的步骤其实非常简单。（你恐怕会困惑上一条为什么说的那么麻烦。）一般只要发现文件内容有变更时都会不顾后果地把文件传上去。像这样——“我的项目根目录下有文件内容变更了，我要快点提交上去！”
如此会发生一件（或两件）事情：首先，程序员会没有意识地把目录下的垃圾代码文件也上传上去。一些人看到类似下面的窗口时，就会点击“选择全部”然后提交——这样源仓库里就会被本不应该存在的未调试的文件和其他垃圾文件给弄乱。

或者是，程序员实际上并没有检查他们更改过什么就把文件上传了。当你在工作中处理配置文件或项目定义文件时很容易就不经意把那些不想提交的文件给上传了，而且那些文件很可能就被别的程序员用到了。你真的会记住你在配置文件里的所有更改吗？

解决方法很简单： 你必须在提交前立刻检查你改过什么地方。做起来其实比听起来还要容易。使用许多系统已经提供的“忽略”特性可以大幅度地减轻“不经意上传文件”的危险。你可以忽略Thumbs.db文件因为你压根不想上传它。你在每次修订后可能还有其他文件不想上传——那么就忽略掉它们吧！
至于文件里的更改，你通常可以使用某个流行的文本比较工具来观察差异。为什么我又要上传一次Web.config文件呢？

噢，我想起来了，我想把尝试密码失败的最大次数从5次减少到3次。啊，我差点没注意把一个虚拟的登录页面给上传上去了。这种在提交前做检查的练习可以让你更容易理解下一节的内容。

• 4、写提交信息时一定要认真
  这是一个古老的谚语（出处不详），大意是说“写每一条提交信息时就好象等下会读到它的人是一个斧头杀人狂，而且他还知道你住在哪里”。如果我是那个杀人狂并在研究你的代码想追踪bug的话，看到的提交信息全部都是“代码更新了”，小心，我会来砍你的！
  我的解决办法就是解释清楚为什么要提交新的代码。每次你对代码进行更改都是有原因的。可能什么地方会崩溃。可能客户不喜欢现在的主题颜色。可能你仅仅要调整一下构建配置。无论是什么，这都是有原因的而且你要把原因用文字保留下来。
  为什么？这样做的原因有很多，而且在不同环境下各不相同。举个例子，使用“归属”特性或其他类似的功能显示出谁改了代码那些地方。如果我不记得18 个月之前我对项目的Web.config文件改过什么地方或者我为什么要改动应用程序的设置，是因为我没有在当时留下一个适当的提交信息，而现在会非常简 单：
  

  
  
  这是一个可以随时观察代码更改的软件的一种。无论我像下面那样想了解一个文件的完整更改历史，还是只想知道团队昨天做了什么，留下一个描述性的相关记录意味着只要不经意一瞥就能知道是什么情况了。
  
  
  
  最后强调一下，当调试遇到错误时提交信息的重要性是无法估计的。举个例子，在你的集成环境里的最后更新的地方可以找到出错的原因。我的例子是非常显而易见的，不过把信息表示出来可以把很多棘手的问题变得极好解决。
  
  
  
  把这条牢记于心，这里列出一些提交信息的反面教材：
  1.可恶
  2.能跑了
  3.解决了一些混帐问题
  4.解决了
  5.改进了一点bug
  6.上传了
  7.排字错误
  8.修订1024
  好的，我从Stack Overflow网站的哪些是你写过的最差劲的提交信息（译者注：帖子已经被删除了，原因难道是出现了脏话？）帖子里选取了以上内容，不过它们和我以前看过的提交信息并不相同。它们没有告诉你有关代码更改的任何有效信息；它们都是垃圾信息。
  关于提交信息最后要注意的是；同一个程序员之后提交信息绝不能和前面的完全相同。原因很好理解：你向源代码管理 软件提交文件是因为对于上一个版本的代码有东西改变了。你现在的代码和之前的已经不一样了，如果你的提交信息是完整准确的，理论上就不能和前面的相同。如 果是相同的（可能有时真的会这样），日志就会难以阅读，因为没有办法区分两条提交有什么区别。

• 5、你必须自己提交你的更改内容——不能委托他人

听起来很奇怪，但它的确会发生，我看过不止一次，最近的是上周。情况是这样的，源代码库被视为极高的地位。因为很多原因，团队会去追求完美代码的洁 净和单一。为了保持这种神圣的状态，代码只能由某个领头的程序员来提交，他在提交前会小心地整合，审查并（大概会）调整改善代码。

即使站在很远也能很容易评价这个方案。不太频繁的提交（可能一周几次），只有一个脱离团队其他程序员的人来提交，而且不可避免地在这段漫长的无提交时期里会有人的工作会导致项目混乱。非常非常不好。

这样做会有两个错误：首先，源代码管理软件并不意味着它里面代码是神圣不可侵犯的；至少在整个开发周期里是这样的。它应该是团队频繁整合文件，在出错时还原到正常并且共同解决问题的地方。不是自始至终都要这样做，只有在应用程序周期的发布时期为了达到某种状态时才做的。

另一个问题——并且真的是极为关键的——站在程序员的视角，这样等于你压根没有在用源代码管理软件！它等于没有同伴之间的代码整合，没有还原，提交信息没有负责人，什么都没有！你们仅仅是在自己的象牙塔里各自写各自的代码然后等着未来顺便某一天把它交给领导就完事了。

不要这样做。千万不要。

• 6、编译生成的文件不要放进源代码管理软件里

简单地说：在编译运行项目时自动生成的结果文件不要放进源代码管理软件里。对于.Net开发的程序员，主要是"bin"和"obj"文件夹里通常会出现的.dll和.pdb文件。
为什么？因为如果你这样做，你的同事会恨你的。这意味着每当他们从版本控制系统里取下最新文件时会让你的编译文件覆盖掉他们的。这是一个双重噩梦 （你绝不能这样做），在他们下一次编译时就会出问题。而且只要他们重新编译后再把编译文件重新上传上去，同样的问题会以相反的方向再发生一次，不过这次你 是受害者。你肯定不想这样的。
当然另一个问题就是这样做很浪费。这会浪费源代码管理服务器的硬盘空间，会浪费带宽并会通过网络发送时一直潜伏着，而且这样做造成的不可避免的冲突会极度浪费你的时间。
所以我们继续使用之前提到的“忽略”方案。只要把像"bin"和"obj"这样的路径直接忽略掉，一切就真的很轻松了。只要按照这种方法做一次，所有人都会感到开心的。
其实我在写pre-commit hooks时就说到了在版本控制的服务器上不能提交此类文件。当然如果有值得这么做的原因的话，只有这种情况下你可以上传。不过我倾向于不要这么做以免将来会导致某个人在更新时发生冲突。

• 7、不要上传你自己的用户设置

老实说，我认为很多人没有注意到他们把自己的私人设置文件上传到源代码管理软件里了。这样会出现的问题是：许多工具会产生只管理你自己本地配置的文 件。它们只对你有用而且通常和其他人的私人设置文件相异。如果你把它们上传到源代码管理软件里，很快你就会覆盖掉其他人的私人设置文件。这样并不好。
这是一个典型的.NET程序的例子：

假如你没有立刻清理的话，多余出来的就是扩展文件和类型描述，也就是.ReSharper.user文件和.suo（Solution User Option， 解决方案用户选项）两个文件，它们只属于你，对其他人无效。
为了理解这点，我们来看看ReSharper文件：

  
    
      
      
      
      True  
      
    
      
        
         
     

在这个例子里，仅仅是在用户文件里记录了我启动了解决方案分析功能。这只是针对我，我喜欢这个功能，其他人则不一定。通常因为他们用的是老化的便宜的机子，我有点跑题了。关键是我的设置会强制让其他人也执行。我这么做不代表其他人也要这么做。

• 8、附属文件也要集成在一起

这是八诫中的最后一条也是最最重要的一条。当应用程序需要外部的附属文件存在才可以正常运行的话，把那些文件也都放进源代码管理软件里！人们倾向于犯的错误是，在他们拥有自己设置文件和本地附属文件的环境里一切都表现得很好就把东西都上传了，之后觉得没问题了就不管了。但是其他人不能从源代码库里找到同样的附属文件的话，所有东西都会悲剧性地报错。
我想到这点是因为今天从源代码库里拖出某个旧项目并运行它时出现了这样的画面：

我以为NUnit一直在机器上，但这次没有。幸运的是使用NuGet可以快速解决问题，但是没有附属文件的话，不是每次都可以用同样的方式就能轻松解决的。有些情况下，它们并不是公开的，你很难全部都获取到。
我从源代码管理软件里取出的项目运行时之所以会报错是因为我发现"C:\Program Files..."路径下丢失了附属的文件。我花了不少时间用来联系最后更改过它的那个人（很明显他在世界上另一个很远的地方），获取了那个文件，把它放 进"Libraries"文件夹下并把它上传到了版本控制系统里，这样下一个提取文件的人就不需要再这么麻烦了。
当然另一个重要的原因是，如果你在任何一种集成环境里工作时，你的构建服务器不一定安装了那些库。你必须有那些文件才能运行。Doug Rathbone最近写了一篇很好的关于这点的文章Third party tools live in your source control(源代码管理软件里的第三方工具)。并不是非要那样做（我们也善意地评价了效果），不过它确实是一个很方便的建议。
因此推荐每个人第一天就把程序运行所需要的东西全都放进版本控制系统里。

总结

没有哪一条是很难理解的。老实说，它们都很基础：尽快并频繁地提交，确认你提交的东西改了什么，还有东西一定要放进版本控制系统里，解释清楚你的提交信息和确保是你自己提交的，不要忘记附属文件。

引用

• 源代码管理十诫 原文

• 源代码管理十诫 中文版

• 源代码管理规范（SVN篇）-解决问题方法