HEVC参考软件准则（提案JCTVC-H1001）

以下归则强制适用于所有软件实现的工作。不符合这些规则的改变将不被软件协调者接收。

1 版权许可

1.1 版权/许可状态

版权放弃声明不应该被改变。每当增加一个文件，如下所示的相同的版权放弃声明，应该包含在文件的开头。

/* The copyright in this software is being made available under the BSD
 * License, included below. This software may be subject to other third party
 * and contributor rights, including patent rights, and no such rights are
 * granted under this license.  
 *
 * Copyright (c) 2010-2012, ITU/ISO/IEC
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  * Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *  * Neither the name of the ITU/ISO/IEC nor the names of its contributors may
 *    be used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 * THE POSSIBILITY OF SUCH DAMAGE.
 */

2 语法的使用

2.1 语言

2.1.1 使用C++。

2.2 模板

2.2.1 不要过度使用模板。仅仅在简单函数中使用它们，像min()和max()那样的很容易理解且可以避免代码重复的地方使用。

2.3 预处理宏

2.3.1 不用用#define来定义函数。用静态或静态内联函数替代。它们远远更不容易出现逻辑错误，且编译器甚至可以更好地优化它们。

2.3.2 不用用#define来封装bug修复。如果bug修复又需要被移除，可以使用版本控制系统跟踪回来（见段落6.1）。

2.3.3 避免使用#define仅仅用来作为一个工具的开关。用一个config文件选项替换，除非会显著放慢代码运行速度。

2.4 头文件多次包含安全

2.4.1 所有的头文件都将使用一个#define来防止多次包含。#define的名字为：前缀”_HM_“、以大写字母开头的头文件名、一个拖尾下划线。文件名中的所有特殊字符用下划线替换。

对于一个名为myheader.h的头文件，代码结构如下：

#ifndef _HM_MYHEADER_H_
#define _HM_MYHEADER_H_

<content of header file>

#endif

2.5 private和protected访问权限

2.5.1 成员变量和方法尽可能为private。只有需要从外部调用的方法应该为public。成员变量都应为private。

2.6 数据类型

2.6.1 使用定义在TypeDef.h中的基本类型（例如Char，Int等）

2.6.2 为整形变量使用Int类型，除非有很好的不用的理由（例如过度的内存占用）。避免使用无符号类型，因为它们可能是bug的来源（例如当有符号与无符号作比较时）

2.6.3 不要使用长整型（long），因为它不是机器独立的（可能32或64位宽）。如果需要一个64位的变量，使用Int64类型。

2.7 不用的代码

不使用的代码将从原代码中完全移除。不允许注释掉或使用值为false的#define条件编译。老版本在版本控制系统中保留。

2.8 代码重复

2.8.1 避免代码重复。在合适的时候定义函数，尽可能地将#define的作用域局部化。

2.9 优化

2.9.1 不要试图去干编译器干的活（优化代码）。让代码易读易维护。

2.9.2 避免使用显式函数内联；在CPP文件中定义函数和方法，除非它们真的非常短。

3 命名

3.1 常规

3.1.1 类、方法、函数、变量都应该是描述性的有意义的名字，描述它们的功能和目的。

3.1.2 所有的类型名（类，结构，枚举，共用，类型别名）应该是名词，且首字母大写。

3.1.3 方法和函数应该是动词，描述一种活动，且首字母小写。

3.1.4 变量名必须以小写字母开头。

3.1.5 新的变量名不使用类型前缀（像iVar，uiVar等等）。当数据类型发生变化而变量名未改时会带来困惑（例如在依赖于不同的宏的时候）。

3.1.6 在所有情况下，应该用骆驼拼写法连接多个单词，一个命名中的每一个后序的单词都应以大写字母开头。

例如：

class CodingTool
{
  Void doSomething()
  {
    <code here>
  }

  Void* m_privateMember;
};

const Int[] g_someTable = { 1, 2, 3, 4 };

3.1.7 全局变量应以前缀“g_”开头。

3.1.8 成员变量应以前缀“m_”开头。

例如：

UInt g_globalVariable;

struct Foo
{
  Int m_memberVariable;
}

4. 格式

4.1 缩进

4.1.1 所有的包含在花括号里的块都必须以2个空格符缩进，从不使用Tab键。

例如：

Void doSomething()
{
  <code here>
}

4.2 花括号的使用和放置

4.2.1 条件式的语句后面的代码总是应该用大括号括起来，尽管是在只有单条语句的情况下。

4.2.2 左大括号放在关键词（void，if，for，while等等）的下一行相同缩进的地方。包含的代码块再从下面一行的缩进开始。右括号放在跟左括号相同缩进的地方。

例如：

Void doSomething ()
{
  if (<expression>)
  {
    <code here>
  }
}

5. 代码注释

5.1 常规

5.1.1 不要使用注释或其他手段来标记你的代码。版本控制系统允许追溯到谁提交的代码（见段落6.2.1）。

5.1.2 使用注释来解释意图不明显的代码片段的意图。注意对第一次读这段代码的用户可能有不同意思的片段。

5.2

5.2.1 使用doxygen文档系统可以形成一种通用的注释风格。这个系统提供了一系列文档命令，用来从外部文档抽取信息。于是就用这些注释强制统一了文档结构。一个额外的特性是，我们可以得到一个完整的格式排版清楚的工程文档。

关于doxygen的进一步的描述，请看文档VCEG-N47，作者的主页http://www.doxgen.org。
例如：

/*! A documentation comment       (in C   style) */
//! Another documentation comment (in C++ style)

//! Documenting the following variable
Int variable1;

Char variable2;    /*!< Documenting the variable before */
Char variable3;    //!< Documenting the variable before

5.3. 文件和函数头

5.3.1 在每个文件的开头或函数定义的前面会放置一个注释头。使用下面的模板，并填入合适的信息：

文件头：

/*! 
 *************************************************************************************
 * \file <filename>
 *
 * \brief
 *    <short description> 
 *
 *************************************************************************************
 */

\file	Name of source file
\brief	Short description

函数头：

/** Short one sentence description, eg counts number of apples in a FruitList.
 * \param fruit pointer to list of fruit to examine
 * \returns number of apples
 *
 * Long description
 */
Int countApples(const FruitList *fruit)

\param	Parameter description
\returns	Description of return values (should be used only for functions that return a value)
\note	Notes (optional)

6. 编译器警告

6.1.1 贡献的代码在以下编译器和标志位编译时，不能产生编译警告

g++-4.1	-Wall
MS Visual C++ 2008	as provided in the workspace

7. 版本控制系统

7.1 常规

7.1.1. 所有软件通过版本控制系统管理。

7.1.2. 提交的补丁应该仅仅是一个单独的逻辑“改变”，例如，一个特性，一个bug修复，等等。

7.1.3. 如果重构，尽量首先提供一个重构提交。