问题标签 [google-style-guide]

我在Google 的 Python 样式指南中阅读了以下内容：

“避免嵌套函数或类，除非关闭局部值”。

“关闭局部值”是什么意思？

完整的相关部分如下：

2.6 嵌套/局部/内部类和函数

当用于关闭局部变量时，嵌套的局部函数或类很好。内部课程很好。

2.6.1 定义

类可以在方法、函数或类中定义。可以在方法或函数内部定义函数。嵌套函数对封闭范围中定义的变量具有只读访问权限。

2.6.2 优点

允许定义仅在非常有限的范围内使用的实用程序类和函数。非常ADT-y。常用于实现装饰器。

2.6.3 缺点

嵌套类或本地类的实例不能被腌制。嵌套函数和类不能直接测试。嵌套可以使您的外部函数更长且可读性更低。

2.6.4 决定

他们很好，有一些警告。避免嵌套函数或类，除非关闭局部值。不要嵌套函数只是为了对模块的用户隐藏它。取而代之的是，在模块级别使用 _ 作为其名称的前缀，以便测试仍然可以访问它。

谷歌风格指南需要导入模块。假设我有一个非平凡的类和几个非平凡的派生类。看来我必须将它们全部放在一个文件中，否则在使用它们时将不得不使用不同的前缀。

我个人更喜欢每个文件一个类。有没有避免不必要的大文件的常用习语？

例如，只要没有名称冲突，我可以将多个导入重命名为一个吗？

我找到了 Google C# 风格指南和这些要点

对于输入，请尽可能使用最严格的集合类型，例如 IReadOnlyCollection / IReadOnlyList / IEnumerable 当输入应该是不可变的时作为方法的输入。

对于输出，如果将返回容器的所有权传递给所有者，则首选 IList 而不是 IEnumerable。如果不转让所有权，请选择最严格的选项。

关于我无法理解的收藏。

1. a) 他们对最严格的收集意味着什么？我想它们暗示接口的继承如下：IReadOnlyList<T>inherits IReadOnlyCollection<T>which inherits IEnumerable<T>。那么IEnumerable是最严格的吗？

   b) 最重要的是为什么这很重要？在任何时候任何人都可以将上述集合转换为List<T>并更改内容 - 我认为没有理由选择“最严格的选项”

2. 他们是否只需要返回接口？这是否意味着我必须始终投向List<T>-IEnumerable<T>这不是误导或打击表现吗？

3. 他们提到转让所有权。我什么时候想转让所有权，什么时候不想转让？如果我这样做为什么

我正在编写一个包含管理信息的分层树。每个正在运行的程序实例有一个树实例。在 C++ 中，我会将树的根作为指向静态对象的私有指针。然后有静态方法通过名称、索引等在树中查找/添加/删除元素。

在 google-style-guide for python 中强烈建议不要这样做？这是可以理解的，但如何在实践中做到这一点？

我能想到的唯一方法是将树的根传递给需要访问树的每个函数。而且看起来也不是很吸引人。

作为初学者，我应该使用标准指南、流行风格指南还是应该根据自己的喜好创建自己的文件？

根据Google C++ Style Guide - Static and Global Variables，

销毁决定

...
因此，我们只允许具有静态存储持续时间的对象，如果它们可以轻易破坏。

常见模式

...

• 映射、集合和其他动态容器：...如果您确实更喜欢标准库中的动态容器，请考虑使用函数局部静态指针，如下所述。
• 如果所有其他方法都失败了，您可以使用函数局部静态指针或引用（例如，static const auto& impl = *new T(args...);）动态创建一个对象并且永远不要删除它。

据我所知，动态分配的对象永远不会被释放。
当程序结束时，操作系统将释放每个未释放的对象，但这不是正确的方法。
为什么不删除动态分配的对象是一个可选选项？

• 根据https://google.github.io/styleguide/cppguide.html#Variable_Names，类的数据成员，无论是静态的还是非静态的，都像普通的非成员变量一样命名，但后面带有下划线。
• 根据https://google.github.io/styleguide/cppguide.html#Constant_Names，“声明为 constexpr 或 const 的变量，其值在程序期间固定，以前导“k”命名，后跟混合案子。” --注意“在程序期间”部分。
• 根据https://google.github.io/styleguide/cppguide.html#Access_Control “使类的数据成员私有，除非它们是常量。这简化了关于不变量的推理，但代价是访问器形式的一些简单样板（通常是 const），如果有必要的话。”

所以......我认为这留下了一些解释空间，我想知道是否有人知道标准的精神是什么......

1. 尾随下划线是“私人”还是“阶级”的标志？
2. const 字段应该是“kSize”还是“size_”？
3. 如果移到公开，应该是“大小”吗？

以下 C++ 中的代码片段在使用 格式化时clang-format-8，在第一次运行时给出不正确的结果（不尊重ColumnWidth=80），在第二次和后续运行中给出正确的结果。注意：代码在注释中包含选项卡（没有使用空格缩进的东西，因为它们只是注释）。似乎ReflowComments没有按预期工作。为什么会这样以及如何处理这种情况，尤其是当我们需要重排长注释并合并不同git分支中先前格式化代码的更改时。

clang-format-8 -style=Google -i src/test.cpp

格式化版本 1（不正确）

格式化版本 2（不正确）

我正在尝试遵循文档字符串的 Google 样式，但是当存在添加/更新属性的函数时，我不确定如何记录函数（以及类本身）。目前我有这样的事情：

但我认为生成的文档（使用 sphinx 与 sphinx_rtd_theme 和 sphinx.ext.napoleon 扩展名）。由于我在 class 和 中都有 docstring，因此__init__我将 napoleon_include_init_with_doc 设置设置为 True。但同样，文档看起来很笨拙且难以理解。我尝试在 Google Style Guide 中找到最佳实践，但找不到好的指导。在这种情况下是否有最佳实践？

我一直在阅读本指南，以编写带有 numpy ndarrays 类型提示的 Google 风格和 Numpy 风格的文档字符串。在 Numpy 样式的文档字符串示例中，类型提示缩写为“np.ndarray”。但是，在相应的 Google 样式示例中，类型写为“numpy.ndarray”。

是否可以将“np.ndarray”用作 Google 样式的文档字符串中的一种类型，或者必须完整地写出“numpy.ndarray”？

我还没有找到任何其他在 Google 样式的文档字符串中使用的 numpy 类型的示例，但我确实看到了一个完整写出“pandas.dataframe”的示例。

如果可以同时使用两者，根据 Google 风格的指南，哪个是正确的？

我在 sphinx 中使用拿破仑扩展来生成自动文档。

另外，我不确定是否在上面的正确上下文中使用“类型提示”。python 文档字符串中的类型规范称为“类型提示”，还是仅用于 python 语言本身的实际类型提示的名称？