这样写python注释让代码更加的优雅-巨人网络通讯

这样写python注释让代码更加的优雅

python这样注释，让你的代码看起来更加的优雅，是不是常常感觉自己的python代码写出来，看起来特别的乱，虽然可以正常运行，但是在优雅性上似乎欠缺的很多，这篇文章主要教你，如何让你的python代码看起来更加的优雅与美观，

一、注释欣赏

这里有一段飞兔小哥哥自己常写的注释模版

这里主要分为表头注释、类注释、欢迎语以及方法注释

表头注释会标注这个项目的名称、文件名、项目作者、时间等基础信息

类注释会标注这个类主要用来做什么的

而方法注释则表示当前方法的作用

#!/usr/bin/env python
# encoding: utf-8
'''
#-------------------------------------------------------------------
#                   CONFIDENTIAL --- CUSTOM STUDIOS
#-------------------------------------------------------------------
#
#                   @Project Name : the desc of project
#
#                   @File Name    : main.py
#
#                   @Programmer   : autofelix
#
#                   @Start Date   : 2021/06/01 12:42
#
#                   @Last Update  : 2021/06/01 12:42
#
#-------------------------------------------------------------------
'''
import requests, os, platform, time
from Crypto.Cipher import AES
import multiprocessing
from retrying import retry
 
class M3u8:
    '''
     This is a main Class, the file contains all documents.
     One document contains paragraphs that have several sentences
     It loads the original file and converts the original file to new content
     Then the new content will be saved by this class
    '''
    def __init__(self):
        '''
        Initial the custom file by self
        '''
        self.encrypt = False
 
    def hello(self):
        '''
        This is a welcome speech
        :return: self
        '''
        print("*" * 50)
        print(' ' * 15 + 'm3u8链接下载小助手')
        print(' ' * 5 + '作者: autofelix  Date: 2021-06-01 12:42')
        print(' ' * 10 + '适用于非加密 | 加密链接')
        print("*" * 50)
        return self
 
    def run(self):
        pass
 
if __name__ == '__main__':
    M3u8().hello().run()

附：python函数注释规范

首先来两段优秀开源框架的代码注释

例1 tornado.web.RequestHandler的get_arguments函数.

 def get_argument(self, name, default=_ARG_DEFAULT, strip=True):
        """Returns the value of the argument with the given name.

        If default is not provided, the argument is considered to be
        required, and we raise a `MissingArgumentError` if it is missing.

        If the argument appears in the url more than once, we return the
        last value.

        The returned value is always unicode.
        """
        return self._get_argument(name, default, self.request.arguments, strip)

例2 requests的get函数

def get(url, params=None, **kwargs):
    """Sends a GET request.

    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response Response>` object
    :rtype: requests.Response
    """

    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

对比下例1和例2, tornado框架的函数倾向与给出函数的用途说明，而不提供具体的输入参数说明，并且相对来说函数名字也是浅显易懂，而requests库看起来比较简洁一点，具体的输入和输出都给的很完整，看起来很是赏心悦目，所以我个人更偏向于例2的注释，当然，也有将例1和例2注释特点结合起来的库，比如tensorflow库，因为涉及的输入参数以及函数较为复杂，因此输入参数和函数原理有较为详尽的说明。总之，大部分编写函数的时候参考例2的注释方式，代码也看起来较为优雅，而遇到比较复杂的情况，则可以参考例1加上必要的函数详细说明。