Python注释规范最佳实践_pycharm函数规范注释

# -*- coding: utf-8 -*-
"""
-------------------------------------------------
   开发人员：Edwin
   开发日期：2020-12-07
   开发工具：PyCharm
   功能描述： 最佳实践是，文件顶部使用多行注释较为完美，也容易跟函数，类进行区分。
            函数与类内部第一行用多行注释生成文档，统一采用这样的方法。也有一些架构师
            用双引号的多行注释表示模块注释，单引号多行用于类和函数，似乎较为完美，但
            这样的规定似乎过于严苛，甚至有点费秒，暂时不进行区分。
            为了方便阅读程序而不生成文档，注释一概写在内部用单行注释。
            遵照python的设计初衷，最好的路当下只有一条。去除多样化。
            文档内直接定义的变量起一个有意义的名字。
   
-------------------------------------------------
"""
# Functuous
# 注释放在方法名前，使用#号注释
def annotation1():
    print("注释放在方法名前")
 
# 注释放在方法名前，使用#号注释
def annotation2():
    """
    既有#号又有多行注释，优先展示多行注释
    """
    print("既有#号又有多行注释时，优先展示多行注释 ")
"""
函数上方用多行注释会显示到哪里呢？实际上哪里也不显示。
"""
def annotation3():
    # 方法内首行使用#注释不生效
    print("方法内首行使用#注释不生效")
 
"""
类上方用多行注释会显示到哪里呢？实际上哪里也不显示。
"""
class AnnClass():
    """
    注释生效顺序与方法一致，优先展示类下的多行注释，如果没有才展示类上面的#号注释
    类下方法注释与函数一致
    """
    def function1(self):
        #类下方法注释不展示
        print("类下的第一个方法")
    def function2(self,a):
        '''
        当输入三个撇后，pycharm自动输出如下，很多人喜欢用@param，既然平台如此提供就先采用
        :param a:参数
        :return:None
        '''
        print("类下的第二个方法")
    # 井号注释
    def function3(self):
        print("显示井号注释")
 
# 变量的注释不会展示出来
a = 1
'''
变量无论用单行还是多行都不能在文档中显示注释，那么我们只能起一个比较有意义的名字
即使此处用了多行注释，其实pydoc并没有生成文档
'''
dbConn = '数据库连接'
'
运行
运行