TensorFlow 代码样式指南

Python 样式

遵循 PEP 8 Python 样式指南,但 TensorFlow 使用 2 个空格而不是 4 个空格。请遵循 Google Python 样式指南,并使用 pylint 检查您的 Python 更改。

pylint

要安装 pylint 并检索 TensorFlow 的自定义风格定义,请运行以下命令:


$ pip install pylint
$ wget -O /tmp/pylintrc https://raw.githubusercontent.com/tensorflow/tensorflow/master/tensorflow/tools/ci_build/pylintrc

要使用 pylint 检查文件,请运行以下命令:

$ pylint --rcfile=/tmp/pylintrc myfile.py

支持的 Python 版本

TensorFlow 支持版本 >= 3.5 的 Python。有关详细信息,请参阅安装指南

有关官方和社区支持的构建,请参阅 TensorFlow 持续构建状态

C++ 编码样式

对 TensorFlow C++ 代码的更改应符合 Google C++ 样式指南。使用 clang-format 检查您的 C/C++ 更改。

要在 Ubuntu 16+ 上安装,请运行以下命令:

$ apt-get install -y clang-format

您可以使用以下命令检查 C/C++ 文件的格式:

$ clang-format <my_cc_file> --style=google > /tmp/my_cc_file.cc
$ diff <my_cc_file> /tmp/my_cc_file.cc

其他语言

TensorFlow 惯例和特殊用法

Python 运算

TensorFlow 运算是一种给定输入张量、返回输出张量(或在构建计算图时向计算图添加运算)的函数。

  • 第一个参数应当是张量,然后是基本的 Python 参数。最后一个参数是默认值为 Nonename
  • 张量参数应当是单个张量或者多个张量的可迭代对象。也就是说,“张量或张量列表”过于宽泛。请参见 assert_proper_iterable
  • 如果使用张量作为参数的运算正在使用 C++ 运算,则应调用 convert_to_tensor 将非张量输入转换为张量。请注意,参数在文档中仍被描述为特定 dtype 的 Tensor 对象。
  • 每个 Python 运算都应具有一个 name_scope。如下所示,以字符串形式传递运算的名称。
  • 运算应包含带参数和返回声明的大量 Python 注释,这些注释说明了每个值的类型和含义。应在说明中指定可能的形状、dtype 或秩。请参阅文档详细信息。
  • 为提高可用性,“示例”部分中包括带运算的输入/输出的用法示例。
  • 避免显式使用 tf.Tensor.evaltf.Session.run。例如,要编写依赖于张量值的逻辑,请使用 TensorFlow 控制流。或者,将运算限制为仅在启用 Eager Execution 时 (tf.executing_eagerly()) 才运行。

示例:

def my_op(tensor_in, other_tensor_in, my_param, other_param=0.5,
          output_collections=(), name=None):
  """My operation that adds two tensors with given coefficients.

  Args:
    tensor_in: `Tensor`, input tensor.
    other_tensor_in: `Tensor`, same shape as `tensor_in`, other input tensor.
    my_param: `float`, coefficient for `tensor_in`.
    other_param: `float`, coefficient for `other_tensor_in`.
    output_collections: `tuple` of `string`s, name of the collection to
                        collect result of this op.
    name: `string`, name of the operation.

  Returns:
    `Tensor` of same shape as `tensor_in`, sum of input values with coefficients.

  Example:
    >>> my_op([1., 2.], [3., 4.], my_param=0.5, other_param=0.6,
              output_collections=['MY_OPS'], name='add_t1t2')
    [2.3, 3.4]
  """
  with tf.name_scope(name or "my_op"):
    tensor_in = tf.convert_to_tensor(tensor_in)
    other_tensor_in = tf.convert_to_tensor(other_tensor_in)
    result = my_param * tensor_in + other_param * other_tensor_in
    tf.add_to_collection(output_collections, result)
    return result

用法:

output = my_op(t1, t2, my_param=0.5, other_param=0.6,
               output_collections=['MY_OPS'], name='add_t1t2')