【Python开发手册】深入剖析Google Python开发规范:规范Python注释写作

这篇具有很好参考价值的文章主要介绍了【Python开发手册】深入剖析Google Python开发规范:规范Python注释写作。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

  • 💖 作者简介:大家好,我是Zeeland,全栈领域优质创作者。
  • 📝 CSDN主页:Zeeland🔥
  • 📣 我的博客:Zeeland
  • 📚 Github主页: Undertone0809 (Zeeland) (github.com)
  • 🎉 支持我:点赞👍+收藏⭐️+留言📝
  • 📣 系列专栏:Python系列专栏 🍁
  • 💬介绍:The mixture of software dev+Iot+ml+anything🔥

本文节选自笔者博客: https://www.blog.zeeland.cn/archives/5h192hdzx

前言

在Python编程中,注释的作用不仅仅是解释函数或代码块的作用,还可以提高可读性、可维护性和表达代码意图的清晰性。正确书写Python注释,既是程序员的编程规范,更是提高代码质量的必要措施。因此,本文总结了Python注释的写法规范和注意事项,以及如何利用Pycharm代码模板快速生成规范注释的方法,帮助广大程序员提高代码质量和效率。

Python注释写作规范

  1. 用#开头,紧跟一个空格,然后是注释内容。
  2. 注释应该描述清楚代码的意图,避免出现无用的信息。
  3. 注释应该写在代码上方或右侧,避免在代码中间插入注释。
  4. 长注释应该使用多行注释,用三个双引号或单引号将注释括起来。
  5. 注释应该使用英文,并且遵循正确的语法和拼写规则。

Google Python开发规范注释示例

在Google Python Style Guide中,函数下面的注释,也称为docstring,应该遵循以下规范:

  1. 函数应该在其定义之前加上注释,用以描述函数的作用和功能。

  2. 函数注释应该包括以下内容:

    • 函数的输入参数和类型;
    • 函数的输出结果和类型;
    • 函数的作用和实现细节;
    • 函数的示例代码。
  3. 函数注释应该遵循Google自己定义的文档字符串格式,即以"""开头和结尾,第一行是概述函数作用的简短语句,接下来是更详细的描述性文本行。

  4. 对于函数参数和返回值的注释,应该使用类型提示来指定参数和返回值的类型,并在注释中提及。

docstring应该在函数定义的第一行后面紧随着出现,用三个引号围起来,格式如下:

def function_name(parameter1, parameter2):
    """
    This is a docstring. It should briefly describe the function and
    its parameters, and possibly give some examples of usage.

    Arguments:
    - parameter1: A description of the first parameter
    - parameter2: A description of the second parameter

    Returns:
    A description of the return value or None if the function doesn't return anything
    """
    # Function body here

docstring应该包括函数的描述、参数和返回值的描述:

  • 函数的描述应该简洁明了,阐述函数的作用、输入和输出。
  • 参数的描述应该使用文本和类型标注来标识各个参数的作用和类型。
  • 返回值的描述应该明确地描绘函数返回的值,包括类型和可能的值范围。

Pycharm代码模板使用方法

如下图,在pycharm定义函数时,单/双三引号添加函数注释,pycharm会自动帮助生成注释模板。个人觉得不是很美观,用着不习惯。

经查阅,该注释模板可以自定义,也有现成的常用注释模板格式供选择。

后来发现直接选择现成注释模板更方便,比如“Google”注释模板格式。相比而言,自定义方法显得繁琐,而且个人觉得没必要花这时间。

以下是选择现成常用注释模板格式的方法:

在pycharm窗口中,依次选择:File→Setting→Tools→Python Integrated Tools→Docstrings→Docstring format: 在下拉菜单中选择“Google” 或是其他你喜欢的格式。

效果如下:

遇到的问题和解决方案

在使用Pycharm代码模板时,有时会遇到代码模板无法自动替换参数值的情况。这时,需要检查代码模板中各个参数的名称和占位符是否正确,或者检查输入参数时是否有语法或拼写错误。另外,也可以在编辑器中手动输入注释,避免使用代码模板。

结论

Python注释的规范性和准确性对于程序员来说是非常重要的,它不仅提高了代码的可读性和可维护性,而且提高了开发效率和协作能力。在编写Python代码时,我们应该遵循规范的注释书写方法,并根据自己的需要来选择合适的工具,如Pycharm代码模板,来帮助我们更快地完成代码注释。文章来源地址https://www.toymoban.com/news/detail-415496.html

到了这里,关于【Python开发手册】深入剖析Google Python开发规范:规范Python注释写作的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 04.阿里Java开发手册——注释规约

    【强制】 类、类属性、类方法的注释必须使用 Javadoc 规范,使用 /**内容*/ 格式,不得使用 // xxx 方式。 说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义

    2024年01月16日
    浏览(43)
  • 开发手册|Java后端开发规范重点条目整理

    Ps:部分熟知的开发规范未收录在本文中!暂无排版格式,等待后续添加…… 1.1 命名风格 代码中的命名严禁使用拼音与英文混合的方式 alibaba / taobao / youku / hangzhou 等国际通用的名称可视同英文 类名使用大驼峰的形式命名,例如 UpperCameCase 方法、参数与变量使用小驼峰的形式

    2024年02月14日
    浏览(44)
  • 阿里巴巴_java开发规范手册详解

    反例: _name, $name, __name 说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,纯拼音命名方式更要避免采用。 正例:renminbi / alibaba / taobao / youku / hangzhou 等国际通用的名称,可视同英文。 反例:DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3 正例:

    2024年02月06日
    浏览(47)
  • 初识Python(注释、编码规范、关键字...)

    🥇 作者简介:CSDN内容合伙人、新星计划第三季Python赛道Top1 🔥 本文已收录于Python系列专栏: 零基础学Python 💬订阅专栏后可私信博主进入Python学习交流群,进群可领取Python视频教程以及Python相关电子书合集 私信未回可以加V:hacker0327 备注零基础学Python 订阅专栏附赠此专栏

    2024年04月11日
    浏览(46)
  • 零基础学Python(3)— 注释、代码缩进和编码规范

    前言: Hello大家好,我是小哥谈。 在使用Python语言进行编程的时候,需要遵循一定的规范标准。本节课就带大家了解下Python语言在注释、缩进和编码方面的规范!~🌈         目录 🚀1.注释 🚀2.代码缩进 🚀3.编码规范 🚀1.注释 在Python中,通常包括 3种 类型的注释,分别是

    2024年01月21日
    浏览(51)
  • 初识Python(注释、代码缩进、编码规范、标识符、变量)

    ✅作者简介:CSDN内容合伙人、阿里云专家博主、51CTO专家博主、新星计划第三季python赛道Top1🏆 📃个人主页:hacker707的csdn博客 🔥系列专栏:零基础入门篇 💬个人格言:不断的翻越一座又一座的高山,那样的人生才是我想要的。这一马平川,一眼见底的活,我不想要,我的人

    2023年04月08日
    浏览(150)
  • 【100天精通python】Day2:python入门_ python的语言基础,编码规范,代码注释,缩进,保留字,标识符

    目录  1 编码规范 1.1 编码规范准则 1.2 编码规范示例 2  代码注释 3  缩进

    2024年02月13日
    浏览(57)
  • SurfaceControl之Transaction事物深入剖析-android framework实战开发

    前面已经讲解清楚了SurfaceControl整个创建过程,一般SurfaceControl都是一个静态图层的代表,但往往只有静态一个图层是没有意义的,即只是创建了一个图层其实啥也看不到,更多需要是SurfaceControl对应的Transaction,这个事务才是真正可以让SurfaceControl可以显示的关键所在,Transac

    2024年01月24日
    浏览(43)
  • 深入理解 python 虚拟机:字节码教程(3)——深入剖析循环实现原理

    在本篇文章当中主要给大家介绍 cpython 当中跟循环相关的字节码,这部分字节码相比起其他字节码来说相对复杂一点,通过分析这部分字节码我们对程序的执行过程将会有更加深刻的理解。 我们使用各种例子来理解和循环相关的字节码: 上面的代码对应的字节码如下所示:

    2023年04月15日
    浏览(40)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包