TensorFlow 代码风格指南

Python 风格

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

pylint

要安装 pylint

$ pip install pylint

要使用 TensorFlow 源代码根目录中的 pylint 检查文件

$ pylint --rcfile=tensorflow/tools/ci_build/pylintrc tensorflow/python/keras/losses.py

支持的 Python 版本

有关支持的 Python 版本，请参阅 TensorFlow 安装指南。

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

C++ 编码风格

对 TensorFlow C++ 代码的更改应符合 Google C++ 风格指南 和 TensorFlow 特定的风格细节。使用 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 参数。最后一个参数是 name，其默认值为 None。
  • 张量参数应该是单个张量或张量可迭代对象。也就是说，“张量或张量列表”过于宽泛。请参阅 assert_proper_iterable。
  • 将张量作为参数的操作应调用 convert_to_tensor 将非张量输入转换为张量（如果它们使用 C++ 操作）。请注意，在文档中，参数仍然被描述为特定数据类型的 Tensor 对象。
  • 每个 Python 操作都应该有一个 name_scope。如下所示，将操作的名称作为字符串传递。
  • 操作应包含一个详细的 Python 注释，其中包含 Args 和 Returns 声明，解释每个值的类型和含义。应在描述中指定可能的形状、数据类型或秩。请参阅文档详细信息。
  • 为了提高可用性，在示例部分中包含操作输入/输出的使用示例。
  • 避免显式使用 tf.Tensor.eval 或 tf.Session.run。例如，要编写依赖于张量值的逻辑，请使用 TensorFlow 控制流。或者，将操作限制为仅在启用急切执行时运行 (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')