
作者:麦叔
来源:麦叔编程
加注释无疑是很好的习惯,但是有时候会被滥用。我一直持有以下几个观点:
先来看看什么是docstring
所以docstring是注释,但又不是普通的注释,可以说它具有一定的语义,可以被python的help()函数或者其他代码识别。这些都是注释所不具备的。
要编写更好的代码,最好的习惯之一是看内置库的源代码。这些代码通常都是很经典的。
我们来看看random库的部分源代码:
class Random(_random.Random): """Random number generator base class used by bound module functions.
Used to instantiate instances of Random to get generators that don't
share state.
Class Random can also be subclassed if you want to use a different basic
generator of your own devising: in that case, override the following
methods: random(), seed(), getstate(), and setstate().
Optionally, implement a getrandbits() method so that randrange()
can cover arbitrarily large ranges.
""" VERSION = 3 # used by getstate/setstate def __init__(self, x=None): """Initialize an instance.
Optional argument x controls seeding, as for Random.seed().
""" self.seed(x)
self.gauss_next = None def seed(self, a=None, version=2): """Initialize internal state from a seed.
The only supported seed types are None, int, float,
str, bytes, and bytearray.
None or no argument seeds from current time or from an operating
system specific randomness source if available.
If *a* is an int, all bits are used.
For version 2 (the default), all of the bits are used if *a* is a str,
bytes, or bytearray. For version 1 (provided for reproducing random
sequences from older versions of Python), the algorithm for str and
bytes generates a narrower range of seeds.
""" if version == 1 and isinstance(a, (str, bytes)):
a = a.decode('latin-1') if isinstance(a, bytes) else a
x = ord(a[0]) << 7 if a else 0 for c in map(ord, a):
x = ((1000003 * x) ^ c) & 0xFFFFFFFFFFFFFFFF x ^= len(a)
a = -2 if x == -1 else x elif version == 2 and isinstance(a, (str, bytes, bytearray)): if isinstance(a, str):
a = a.encode()
a = int.from_bytes(a + _sha512(a).digest(), 'big') elif not isinstance(a, (type(None), int, float, str, bytes, bytearray)):
_warn('Seeding based on hashing is deprecatedn' 'since Python 3.9 and will be removed in a subsequent ' 'version. The only n' 'supported seed types are: None, ' 'int, float, str, bytes, and bytearray.',
DeprecationWarning, 2)
super().seed(a)
self.gauss_next = None def getstate(self): """Return internal state; can be passed to setstate() later.""" return self.VERSION, super().getstate(), self.gauss_next def setstate(self, state): """Restore internal state from object returned by getstate().""" version = state[0] if version == 3:
version, internalstate, self.gauss_next = state
super().setstate(internalstate) elif version == 2:
version, internalstate, self.gauss_next = state # In version 2, the state was saved as signed ints, which causes # inconsistencies between 32/64-bit systems. The state is # really unsigned 32-bit ints, so we convert negative ints from # version 2 to positive longs for version 3. try:
internalstate = tuple(x % (2 ** 32) for x in internalstate) except ValueError as e: raise TypeError from e
super().setstate(internalstate) else: raise ValueError("state with version %s passed to " "Random.setstate() of version %s" %
(version, self.VERSION))
类的开头,和方法的开头都有大段的docstring。
我们来试一下docstring的使用。
打开命令行窗口,进入交互式Python。
如下所示,可以看到,我们写的docstring自动成为了一个名为__doc__的属性:
这个属性任何类或函数都有,只不过有的为空。
>>> import random
>>> random.__doc__
'Random variable generators.nn bytesn -----n uniform bytes (values between 0 and 255)nn integersn --------n uniform within rangenn sequencesn ---------n pick random elementn pick random samplen pick weighted random samplen generate random permutationnn distributions on the real line:n ------------------------------n uniformn triangularn normal (Gaussian)n lognormaln negative exponentialn gamman betan pareton Weibullnn distributions on the circle (angles 0 to 2pi)n ---------------------------------------------n circular uniformn von MisesnnGeneral notes on the underlying Mersenne Twister core generator:nn* The period is 2**19937-1.n* It is one of the most extensively tested generators in existence.n* The random() method is implemented in C, executes in a single Python step,n and is, therefore, threadsafe.nn'
docstring的第二个用法是,可以用help()函数打印出来。如下所示:
Python 3.10.0 (v3.10.0:b494f5935c, Oct 4 2021, 14:59:19) [Clang 12.0.5 (clang-1205.0.22.11)] on darwin
Type "help", "copyright", "credits" or "license" for more information. >>> import random >>> help(random)
这时候屏幕就会展示random模块的docstring,这正是上面代码中的三引号括起来的那一大段:
普通青年写注释,文艺青年用docstring。下一次写类,写函数的时候,尝试使用docstring,而不是使用注释吧。
数据分析咨询请扫描二维码
若不方便扫码,搜微信号:CDAshujufenxi
剖析 CDA 数据分析师考试题型:解锁高效备考与答题策略 CDA(Certified Data Analyst)数据分析师考试作为衡量数据专业能力的 ...
2025-07-04SQL Server 字符串截取转日期:解锁数据处理的关键技能 在数据处理与分析工作中,数据格式的规范性是保证后续分析准确性的基础 ...
2025-07-04CDA 数据分析师视角:从数据迷雾中探寻商业真相 在数字化浪潮席卷全球的今天,数据已成为企业决策的核心驱动力,CDA(Certifie ...
2025-07-04CDA 数据分析师:开启数据职业发展新征程 在数据成为核心生产要素的今天,数据分析师的职业价值愈发凸显。CDA(Certified D ...
2025-07-03从招聘要求看数据分析师的能力素养与职业发展 在数字化浪潮席卷全球的当下,数据已成为企业的核心资产,数据分析师岗位也随 ...
2025-07-03Power BI 中如何控制过滤器选择项目数并在超限时报错 引言 在使用 Power BI 进行数据可视化和分析的过程中,对过滤器的有 ...
2025-07-03把握 CDA 考试时间,开启数据分析职业之路 在数字化转型的时代浪潮下,数据已成为企业决策的核心驱动力。CDA(Certified Da ...
2025-07-02CDA 证书:银行招聘中的 “黄金通行证” 在金融科技飞速发展的当下,银行正加速向数字化、智能化转型,海量数据成为银行精准 ...
2025-07-02探索最优回归方程:数据背后的精准预测密码 在数据分析和统计学的广阔领域中,回归分析是揭示变量之间关系的重要工具,而回 ...
2025-07-02CDA 数据分析师报考条件全解析:开启数据洞察之旅 在当今数字化浪潮席卷全球的时代,数据已成为企业乃至整个社会发展的核心驱 ...
2025-07-01深入解析 SQL 中 CASE 语句条件的执行顺序 在 SQL 编程领域,CASE语句是实现条件逻辑判断、数据转换与分类的重要工 ...
2025-07-01SPSS 中计算三个变量交集的详细指南 在数据分析领域,挖掘变量之间的潜在关系是获取有价值信息的关键步骤。当我们需要探究 ...
2025-07-01CDA 数据分析师:就业前景广阔的新兴职业 在当今数字化时代,数据已成为企业和组织决策的重要依据。数据分析师作为负责收集 ...
2025-06-30探秘卷积层:为何一个卷积层需要两个卷积核 在深度学习的世界里,卷积神经网络(CNN)凭借其强大的特征提取能力 ...
2025-06-30探索 CDA 数据分析师在线课程:开启数据洞察之旅 在数字化浪潮席卷全球的当下,数据已成为企业决策、创新与发展的核心驱 ...
2025-06-303D VLA新范式!CVPR冠军方案BridgeVLA,真机性能提升32% 编辑:LRST 【新智元导读】中科院自动化所提出BridgeVLA模型,通过将 ...
2025-06-30LSTM 为何会产生误差?深入剖析其背后的原因 在深度学习领域,LSTM(Long Short-Term Memory)网络凭借其独特的记忆单元设 ...
2025-06-27LLM进入拖拽时代!只靠Prompt几秒定制大模型,效率飙升12000倍 【新智元导读】最近,来自NUS、UT Austin等机构的研究人员创新 ...
2025-06-27探秘 z-score:数据分析中的标准化利器 在数据的海洋中,面对形态各异、尺度不同的数据,如何找到一个通用的标准来衡量数据 ...
2025-06-26Excel 中为不同柱形设置独立背景(按数据分区)的方法详解 在数据分析与可视化呈现过程中,Excel 柱形图是展示数据的常用工 ...
2025-06-26