当前位置: 首页 > news >正文

【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 andits parameters, and possibly give some examples of usage.Arguments:- parameter1: A description of the first parameter- parameter2: A description of the second parameterReturns: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代码模板,来帮助我们更快地完成代码注释。

相关文章:

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

💖 作者简介:大家好,我是Zeeland,全栈领域优质创作者。📝 CSDN主页:Zeeland🔥📣 我的博客:Zeeland📚 Github主页: Undertone0809 (Zeeland) (github.com)&…...

Python入门教程+项目实战-9.3节: 字符串的操作方法

目录 9.3.1 字符串常用操作方法 9.3.2 获取字符串长度 9.3.3 字符串的大小写操作 9.3.4 删除字符串中的空白字符 9.3.5 字符串的子串查找 9.3.6 字符串的子串统计 9.3.7 字符串的子串替换 9.3.8 字符串的拆分函数 9.3.9 字符串的前缀与后缀9.3.10 知识要点 9.3.11 系…...

ENVI 5.6软件安装教程

软件下载 [软件名称]:ENVI 5.6 [软件大小]:3.25G [安装环境]:Win7~Win11或更高 软件介绍 ENVI 5.6是一款实现遥感图像处理的工具,已经广泛应用于科研、环境保护、气象、石油矿产勘探、农业、林业、医学、地球科学、公用设施管…...

在Windbg中设置断点追踪打开C++程序远程调试开关的模块

目录 1、Windbg动态调试 2、在Windbg中设置断点 2.1、在函数入口处设置断点 2.2、在函数内部某一行上设置断点 3、设置断点跟踪对打开远程调试开关接口的调用 3.1、编写演示代码 3.2、在Windbg中设置调用SetRemoteDebugOn接口的断点进行跟踪 4、最后 VC常用功能开发汇总…...

CRM客户管理软件开发功能有哪些?

互联网技术的不断提高使得企业管理方式也发生了变化,企业CRM系统应用市场逐渐扩大,相关软件开发也引起越来越多商家企业的关注。因为企业CRM系统软件开发能够根据企业需求制作,帮助企业更好的追踪管理客户信息,实时更新并进行相关…...

C++函数式魔法之旅(Journey of Functional Magic)

C函数式魔法之旅(Journey of Functional Magic) 一、引言(Introduction)C Functional模板库简介(Overview of C Functional Template Library)Functional模板库的重要性和作用(The Importance a…...

Vue基础入门(上)

<script src"https://unpkg.com/vuenext"></script> 从面向dom编程到面向数据编程 输入显示列表 const appVue.createApp({data(){return{inputValue:,list:[]}},methods:{handleAddItem(){this.list.push(this.inputValue);this.inputValue;}},templ…...

字符串匹配—KMP算法

字符串匹配的应用非常广泛&#xff0c;例如在搜索引擎中&#xff0c;我们通过键入一些关键字就可以得到相关的搜索结果&#xff0c;搜索引擎在这个过程中就使用字符串匹配算法&#xff0c;它通过在资源中匹配关键字&#xff0c;最后给出符合条件的搜索结果。并且我们在使用计算…...

【微信小程序】 权限接口梳理以及代码实现

​ 1、权限接口说明 官方权限说明   部分接口需要经过用户授权统一才能调用。我们把这些接口按使用范围分成多个scope&#xff0c;用户选择对scope进行授权&#xff0c;当授权给一个scope之后&#xff0c;其对应的所有接口都可以直接使用。 此类接口调用时&#xff1a; 如…...

【每日一词】leit-motif

1、释义 leit-motif: n. 主乐调&#xff1b;主题&#xff1b;主旨。 复数&#xff1a;leit-motifs 2、例句 Hence the ‘ancient’ rhyme that appears as the leit-motif of The Lord of the Rings, Three Rings for the Elven-Kings under the sky, Seven for the Dwarf-lor…...

windows 环境修改 Docker 存储目录

windows 环境修改存储目录 docker 安装时不提供指定安装路径和数据存储路径的选项&#xff0c;且默认是安装在C盘的。C盘比较小的&#xff0c;等docker运行久了&#xff0c;一大堆的东西放在上面容易导致磁盘爆掉。所以安装前可以做些准备&#xff0c;让安装的实际路径不在C盘&…...

上海市青少年算法月赛丙组—目录汇总

上海市青少年算法2023年3月月赛&#xff08;丙组&#xff09; T1 神奇的字母序列 T2 约数的分类 T3 循环播放 T4 数对的个数 T5 选取子段 上海市青少年算法2023年2月月赛&#xff08;丙组&#xff09; T1 格式改写 T2 倍数统计 T3 区间的并 T4 平分数字&#xff08;一&#xf…...

手动实现promise.all

手动实现promise.all function promiseAll(promises) {return new Promise((resolve, reject) > {const results [];let count 0;promises.forEach((promise, index) > {Promise.resolve(promise).then(result > {results[index] result;count;if (count promise…...

如何搭建关键字驱动自动化测试框架?这绝对是全网天花板的教程

目录 1. 关键字驱动自动化测试介绍 2. 搭建关键字驱动自动化测试框架 步骤1&#xff1a;选择测试工具 步骤2&#xff1a;定义测试用例 步骤3&#xff1a;编写测试驱动引擎 步骤4&#xff1a;实现测试关键字库 步骤5&#xff1a;执行测试 3. 实现关键字驱动自动化测试的关…...

字符串反转操作

1:将字符串反转 给定一句英语&#xff0c;要求你编写程序&#xff0c;将句中所有单词的顺序颠倒输出。 输入格式&#xff1a; 测试输入包含一个测试用例&#xff0c;在一行内给出总长度不超过 80 的字符串。字符串由若干单词和若干空格组成&#xff0c;其中单词是由英文字母…...

TensorFlow 智能移动项目:1~5

原文&#xff1a;Intelligent mobile projects with TensorFlow 协议&#xff1a;CC BY-NC-SA 4.0 译者&#xff1a;飞龙 本文来自【ApacheCN 深度学习 译文集】&#xff0c;采用译后编辑&#xff08;MTPE&#xff09;流程来尽可能提升效率。 不要担心自己的形象&#xff0c;只…...

[MAUI 项目实战] 手势控制音乐播放器(四):圆形进度条

文章目录 关于图形绘制创建自定义控件使用控件创建专辑封面项目地址 我们将绘制一个圆形的音乐播放控件&#xff0c;它包含一个圆形的进度条、专辑页面和播放按钮。 关于图形绘制 使用MAUI的绘制功能&#xff0c;需要Microsoft.Maui.Graphics库。 Microsoft.Maui.Graphics 是…...

web路径专题+会话技术

目录 自定义快捷键 1. 工程路径问题及解决方案1.1 相对路径1.2 相对路径缺点1.3 base标签1.4 作业11.5 作业21.6注意细节1.7 重定向作业1.8 web工程路径优化 2. Cookie技术2.1 Cookie简单示意图2.2 Cookie常用方法2.2 Cookie创建2.3 Cookie读取2.3.1 JSESSIONID2.3.2 读取指定C…...

Jetpack Compose 实战 宝可梦图鉴

文章目录 前言实现效果一、架构介绍二、一些的功能点的介绍加载图片并获取主色,再讲主色设置为背景一个进度缓慢增加的圆形进度条单Activity使用navigation跳转Compose可组合项返回时页面重组的问题hiltViewModel() 主要参考项目总结 前言 阅读本文需要一定compose基础&#x…...

高效时间管理日历 DHTMLX Event Calendar 2.0.3 Crack

DHTMLX Event Calendar用于高效时间管理的轻量级 JavaScript 事件日历 DHTMLX 可帮助您开发类似 Google 的 JavaScript 事件日历&#xff0c;以高效地组织约会。 用户可以通过拖放来管理事件&#xff0c;并以六种不同的模式显示它们。 JavaScript 事件日历功能 轻的简单的 Java…...

Redis相关知识总结(缓存雪崩,缓存穿透,缓存击穿,Redis实现分布式锁,如何保持数据库和缓存一致)

文章目录 1.什么是Redis&#xff1f;2.为什么要使用redis作为mysql的缓存&#xff1f;3.什么是缓存雪崩、缓存穿透、缓存击穿&#xff1f;3.1缓存雪崩3.1.1 大量缓存同时过期3.1.2 Redis宕机 3.2 缓存击穿3.3 缓存穿透3.4 总结 4. 数据库和缓存如何保持一致性5. Redis实现分布式…...

全球首个30米分辨率湿地数据集(2000—2022)

数据简介 今天我们分享的数据是全球30米分辨率湿地数据集&#xff0c;包含8种湿地亚类&#xff0c;该数据以0.5X0.5的瓦片存储&#xff0c;我们整理了所有属于中国的瓦片名称与其对应省份&#xff0c;方便大家研究使用。 该数据集作为全球首个30米分辨率、覆盖2000–2022年时间…...

C# 类和继承(抽象类)

抽象类 抽象类是指设计为被继承的类。抽象类只能被用作其他类的基类。 不能创建抽象类的实例。抽象类使用abstract修饰符声明。 抽象类可以包含抽象成员或普通的非抽象成员。抽象类的成员可以是抽象成员和普通带 实现的成员的任意组合。抽象类自己可以派生自另一个抽象类。例…...

学习STC51单片机32(芯片为STC89C52RCRC)OLED显示屏2

每日一言 今天的每一份坚持&#xff0c;都是在为未来积攒底气。 案例&#xff1a;OLED显示一个A 这边观察到一个点&#xff0c;怎么雪花了就是都是乱七八糟的占满了屏幕。。 解释 &#xff1a; 如果代码里信号切换太快&#xff08;比如 SDA 刚变&#xff0c;SCL 立刻变&#…...

10-Oracle 23 ai Vector Search 概述和参数

一、Oracle AI Vector Search 概述 企业和个人都在尝试各种AI&#xff0c;使用客户端或是内部自己搭建集成大模型的终端&#xff0c;加速与大型语言模型&#xff08;LLM&#xff09;的结合&#xff0c;同时使用检索增强生成&#xff08;Retrieval Augmented Generation &#…...

【分享】推荐一些办公小工具

1、PDF 在线转换 https://smallpdf.com/cn/pdf-tools 推荐理由&#xff1a;大部分的转换软件需要收费&#xff0c;要么功能不齐全&#xff0c;而开会员又用不了几次浪费钱&#xff0c;借用别人的又不安全。 这个网站它不需要登录或下载安装。而且提供的免费功能就能满足日常…...

在Mathematica中实现Newton-Raphson迭代的收敛时间算法(一般三次多项式)

考察一般的三次多项式&#xff0c;以r为参数&#xff1a; p[z_, r_] : z^3 (r - 1) z - r; roots[r_] : z /. Solve[p[z, r] 0, z]&#xff1b; 此多项式的根为&#xff1a; 尽管看起来这个多项式是特殊的&#xff0c;其实一般的三次多项式都是可以通过线性变换化为这个形式…...

适应性Java用于现代 API:REST、GraphQL 和事件驱动

在快速发展的软件开发领域&#xff0c;REST、GraphQL 和事件驱动架构等新的 API 标准对于构建可扩展、高效的系统至关重要。Java 在现代 API 方面以其在企业应用中的稳定性而闻名&#xff0c;不断适应这些现代范式的需求。随着不断发展的生态系统&#xff0c;Java 在现代 API 方…...

【前端异常】JavaScript错误处理:分析 Uncaught (in promise) error

在前端开发中&#xff0c;JavaScript 异常是不可避免的。随着现代前端应用越来越多地使用异步操作&#xff08;如 Promise、async/await 等&#xff09;&#xff0c;开发者常常会遇到 Uncaught (in promise) error 错误。这个错误是由于未正确处理 Promise 的拒绝&#xff08;r…...

破解路内监管盲区:免布线低位视频桩重塑停车管理新标准

城市路内停车管理常因行道树遮挡、高位设备盲区等问题&#xff0c;导致车牌识别率低、逃费率高&#xff0c;传统模式在复杂路段束手无策。免布线低位视频桩凭借超低视角部署与智能算法&#xff0c;正成为破局关键。该设备安装于车位侧方0.5-0.7米高度&#xff0c;直接规避树枝遮…...