文章目录

• 1.前言
• 2. 我们惊叹它的什么/li>
• • 2.1 清晰的代码注释
  • 2.2 语义化的编码规范
  • 2.3 小而精的逻辑实现
• 3. 依葫芦画瓢
• • 3.1 添加文档级注释
  • 3.2 添加类级注释
  • 3.3 添加方法级注释
  • 3.4 添加行级注释
  • 3.5 其他小技巧
  • • 3.5.1 查看方法注释
    • 3.5.2 生成说明文档
    • 3.5.3 打包项目所需依赖包
• 4 小结

1.前言

这几天，红警1的开源代码重现江湖，这个20年前，甚至25年前的代码，被我们所有的后来者所惊叹，这才是一个艺术品(art)一般的存在。其优秀的代码才是一款RTS游戏能够风靡全球的最根本保障。
其开源链接为：https://github.com/electronicarts/CnC_Remastered_Collection
如果你想重温这款童年记忆，那么花费140人民币，你就可以在Steam上体验到这款游戏。

但是，我们的重点，主要在其代码上，因此不放出其游戏截图了，而是专注代码。下面是我随便点开的一个文件内容。大家可以欣赏一下什么是赏心悦目的代码。

尽管看起来可能没有红警原版霸气，但是只要学会了这个技术，我们都可以创建属于自己的风格的文件头。我们只需要利用pycharm中的文件模板设置即可。它总共分为3个步骤：
首先，点击File->Settings进入设置界面，选择Editor下的File and Code Templates选项。

当然，更多其他的这种内置变量或者自定义变量的使用方法可以参见《详解pycharm新建文件时头部的模板》。

3.2 添加类级注释

当添加完文件注释以后，我们就需要添加更加细致的注释，首先来看对于类的注释。下面的例子给出了类注释的两个部分，一个部分是直接处于类下的简要介绍，另一个则是在下的注释。两个部分都是使用进行标记的。图上风格为pycharm自带的编码风格，也有google和Numpy风格的注释，详情可以看《python常见的三种注释风格》

3.3 添加方法级注释

更加细致的注释是在方法级的注释，如下面代码所示，它注释在方法上，一个好处是可以直接指导这个函数的功能，另一个好处就是当你在查看方法时，不需要点击方法里面查看源代码，也知道它的用途、参数和返回值，这个操作我们下面会介绍。

3.4 添加行级注释

最细致的是行级注释，只注释在每一个行上，例如刚才出现过的例子。它可以用来解释一些不是很容易知道操作的目的的代码。

3.5 其他小技巧

经过以上4级的注释，我们让代码更加的丰满了，从而能够达到红警里注释的效果。但是我们这东西可不是绣花枕，中看不中用，它是可以实实在在帮助我们提高编程效率的。下面我们介绍一些小技巧来帮助我们更好的利用我们/其他人的注释。

3.5.1 查看方法注释

当我们费了千辛万苦注释完毕后，该怎么查看呢个方法就是将鼠标放置在我们想要查看的方法上，按住，就可以查看到其注释了。

3.5.2 生成说明文档

就像刚才讲的，这些都是在代码里查看的，如果我们想生成一个工业级的软件说明文档该如何呢么多注释不能白写了呀。这时候我们就可以使用Sphinx来帮助我们实现自动化的说明文档生成，详情可以看《Sphinx入门——快速生成Python文档》。

3.5.3 打包项目所需依赖包

当我们代码也准备好了，说明文档也准备好了，距离交付别人就只差一个依赖包了。我们的项目可能会依赖很多第三方的包，如果不给别人一个依赖清单，那么别人也没有办法非常容易的复现你的程序，因为总会报各种各样的错误。这时候，我们又需要另一个神器了。
首先使用命令行执行。
然后进入项目的文件夹里，执行下面的命令：

这样就会生成一个文件，里面就是我们的依赖包了，等到再复现的时候，只需要执行即可重装这些依赖了。

4 小结

至此，我们基本上讲述了如何实现教科书级的红警开源代码需要注意的事项，为以后我们更好的编码打下了基础。在将来，我们将会磨砺自己的编程技巧，终有一天做出一流的艺术品，为整个虚拟世界真真正正的贡献自己的一份力量！

文章知识点与官方知识档案匹配，可进一步学习相关知识Python入门技能树首页概览208411 人正在系统学习中

来源：刘炫320