编程语言通用编码规范

大炮特靠谱

1. 概述

• 【重要性】定义编码规范，是为了提高代码的可阅读性、可维护性。可阅读性也能提高代码的可维护性。
  
• 很多的编码规范的规则与语言的语法无关，在编程工作中是通用的。
  
• 《通用编码规范》是列举编码中对每种开发语言都有帮助的一些规则。
  
• 每种编程语言还有自己的一些规则，大家学习的时候需要注意。
  
• 编码规范很重要，但是不是绝对的。团队认可的、习惯的、能提高团队效率的规则，都是可接受的。
  
• 本文档没有涉及具体语言，可以当成讲座看，并不是某语言的正式编码规范。
  
• 文章中以C#为例。
  

2. 背景知识分享
2.1. Google编码规范

• 链接： Google Style Guides
  

Google提供多种程序语言的编码规范，有兴趣的朋友可以深入学习。


2.2. Pascal命名与Camel命名

• Pascal case: （也叫大驼峰）
  
  
  
  • 例如：
    
    
    
    • DataFormat
      
    • SendMessage
      
    • GameManager
      
    
    
  
  
• Camel case: （也叫小驼峰）
  
  
  
  • 例如：
    
    
    
    • dataFormat
      
    • sendMessage
      
    • gameManager
      
    
    
  
  
• 也还有其它命名规则
  
  
  
  • Kebab case:
    
    
    
    • send-message
      
    • game-manager
      
    
    
  
  

2.3. 匈牙利命名法
匈牙利命名法，该方法出自微软，在变量前加一个前缀，标识变量的类型和作用区域。
例程：

HWND hWnd； CWnd* pWnd； HDLG hDlg； CDialog* pDlg； HDC hDC； CDC* pDC； HGDIOBJ hGdiObj； CGdiObject* pGdiObj； HPEN hPen； CPen* pPen； HBRUSH hBrush； CBrush* pBrush； HFONT hFont； CFont* pFont； HBITMAP hBitmap； CBitmap* pBitmap； HPALETTE hPaltte； CPalette* pPalette；

说明：

• 匈牙利命名法过分注重变量的类型，带来命名的复杂性。
  
• 很多时候，我们关心变量所代表的意义，而不是它的类型，所以C++引入了auto, C #引入了var。
  

2.4. 编码规范与最佳编程实践

• 大家可能常听说编码方面的2个概念：编码规范和x语言最佳编程实践。
  
• 这2个概念，都对编码提出了一些规则，但是它们关注的重点是有区别的。
  
• 编码规范是为了提高代码的可阅读性和可维护性。
  
• 最佳编程实践是为了提高代码的性能和稳定性等方面。
  
  
  
  • 比如C++的变量初始化、小函数最好定义为内联函数，不要硬编码等等。
    
  
  

3. 编码规范 - 命名规范
3.1. 命名要有意义！！！

• <命名很重要>
  
• <命名要有意义>
  
• 编码规范里，命名是最最核心的规则
  
• 命名是最好的注释
  
• 命名一定要表达清楚意思
  

3.2. 命名规则

• 项目中涉及到的名字很多，每种名字都应该定义清楚的规则。
  

以C#为例：


3.3. 命名规则技巧

• 全局变量，Public属性等，命名相对完整
  
  
  
  • CalcaluteDistanceFromPointToLine（计算点到线的距离）
    
  • CalculateBattlePower
    
  • GameManager, PlayerActor, UIItemBase
    
  
  
• 函数体内的变量命名，可以相对简单一些
  
  
  
  • int i, j, k;
    
  • float dis;
    
  
  
• 函数命名，以动词、系动词Be等开头：
  
  
  
  • GetXXX()
    
  • CalculateXXX()
    
  • IsDead()
    
  
  
• 慎用缩写，避免歧义
  
  
  
  • 例如：compute, compare, compress, 如果缩写成CompXXX，就不知道Comp代表哪个单词了。
    
  
  
• 文件名建议采用Java文件名命名策略：文件名与类名保持一致。
  

4. 代码格式
4.1. 文件长度

• 文件不宜太长，大概在600行以内。
  
• 如果类太大，可以把这个类的某些属性定义成新的类。
  
• 如果文件太长，C#可以采用采用partial分成多个文件。
  

4.2. 函数体长度

• 函数体不宜太长，大概在60行以内。
  
• 如果函数超过60行，可以考虑把某些代码独立成一个新的函数。
  

4.3. 代码行的长度

• 每行的长度不超过80字符
  

4.4. public, protected, private定义的顺序
原则1：最多人看到的内容，排在前面
原则2：相关的代码，放在临近的地方。比如一个public函数A，调用了private函数B，可以考虑把B直接排在A的后面。结合region更好。
在一个类的代码里，无论变量/属性，还是函数，遵守public，protected，private的顺序。
5. 注释
5.1. 代码的注释很重要
代码里的注释是很重要的。
有的代码命名比较简单，命名中有拼写错误，函数体比较长等等，如果这样的代码还没有注释，其他同事(包括自己)很难看懂这样的代码。
其次注释和代码颜色不同，在代码中添加注释，通过颜色的交替，可以提高代码的可阅读性。
5.2. 几种注释

• 文件注释
  
  
  
  • 添加作者、版权申请、产生日期之类信息
    
  
  
• 类注释
  
  
  
  • 类作用
    
  • 使用这个类需要注意的问题
    
  
  
• 函数定义的注释
  
  
  
  • 函数的作用
    
  • 调用时机
    
  • 函数的输入、输出
    
  • 参数说明
    
  
  
• 函数体的注释
  
  
  
  • 让三个月后，你再看到这段代码的时候，能像三个月前写这段代码的时候一样熟悉它
    
  • 让其他同事快速看懂这段代码，特别是算法。
    
  
  
• TODO注释
  
  
  
  • 例如格式：”[Todo]+[添加人的名字]+[描述]”
    
  
  

6. 后记
欢迎大家交流。

乐途林

啊啊啊啊啊啊啊啊啊啊啊