代码中一些细节问题

• 在定义参数字段时尽量根据实际场景来, 不要定义太通用的字段或者不明确的字段。

  task_id = request.GET.get("id")
  

  建议为:

  task_id = request.GET.get("task_id ")
  

• 格式化尽量使用 f-string 关键字,使更清晰简洁并且在直观性上也很突出, 最重要的一点是 f-string 是 python
  三种格式化方式中效率最高的, 在 python3.6 之后版本的新特性, 使用了新的字节码指令, 底层也进行了优化。

  如: 
  name = "xx"
  age = 20
  f"我是{name}, 今年{age}岁"
  

• 定义空字典时使用 dict(个人观点), 如果定义太多这种 {} 空字典时,代码中就会出现很多字符串, 看起来也不是太优雅, 虽说直接定义 {} 会效率稍高一点。

  a = {
  	"name":"xiaomign",
  	"age": 20,
  	"sex":"男"
  }
  

  a = dict(
  	name="xiaomign",
  	age=20,
  	sex="男"
  )
  

• 合理的换行, 使代码更清晰直观
  像这种挂在哪里很难看, 很不舒服

  if task_time_dict['start_time'] < datetime.datetime.strftime(datetime.datetime.now(),
                                                                               '%Y-%m-%d %H:%M:%S'):
  

  建议:

  date = datetime.datetime.strftime(
  	datetime.datetime.now(),
  	'%Y-%m-%d %H:%M:%S'
  )
  if task_time_dict['start_time'] < date:
  
  # 如果值很长的情况下, 可以一行一个
  a = dict(
  	name="xiaomign",
  	age=20,
  	sex="男"
  )
  

• 相关的代码块尽量放到一起
  这种离得很远, 如果代码很长, 看起来就不太直观

  title = request.GET.get('title')
  author = request.GET.get('author')
  
  if title:
      qs = qs.filter(title__icontains=title)
  
  if author:
      qs = qs.filter(author__icontains=author)
  

  title = request.GET.get('title')
  if title:
      qs = qs.filter(title__icontains=title)
  
  author = request.GET.get('author')
  if author:
      qs = qs.filter(author__icontains=author)
  

• 不要再一个接口中实现两个接口的事情
  见到有人在项目中使用 id 来判断返回的详情数据或是列表数据。

  task_id = request.GET.get("id")
  if task_id:
  	# 返回详情数据
  	...
  else:
  	# 返回列表数据
  	...
  
  

注释规范

写代码注释是一件很重要的事情, 特别是给别人调用的方法都需要配上一些基本的注释信息, 写好代码可以让别人容易阅读, 有句话说的话"编程不规范, 同事两行泪", 恰当的注释会更加好理解一点, 那么什么样的注释才是规范的注释, 才能让其他人快速的了解你的代码结构呢, 这里就谈一谈~~~
python 注释有哪些?

• 单行注释
• 多行注释
• 特殊注释

那些场合使用那些注释?
在 api 中:

1. 需要明确写出改接口是干嘛的

2. 请求路径是什么

3. 参数 QueryString 或是 Body

4. 需要考虑的地方, 可以是需求中的, 也可以是自己考虑到的
   示例:

   @require_http_methods(['POST'])
   @login_required(api=True)
   def activate(request):
       """课程激活
       POST /api/v3/course/activate
   
       Body{
           code='激活码'
       }
   
       需要考虑以下情形：
       * 该激活码已经被使用
       * 该激活码已经失效
       * 该激活码不能叠加使用:同一个批次的激活码,对于同一个用户,只能用一个
       * 错误的激活码
       """
       code = request.json.get('code')
       if not code:
           return api.bad_request('code 不能为空！')
   
       success, note = ActivationCode.activate(request, code)
       if success:
           return api.ok(message=note)
       return api.bad_request(note)
   

在公共的方法中:
5. 这个类/方法是干嘛的?
6. 经常在什么情况下使用?
7. 如何使用?
如果都交代的很详细, 估计别人不看代码都已经会使用了。
示例:

def get_fields(check_object, action=None):
    """获取一个对象的可展示字段和搜索字段，返回一个格式化好的 list()
    :param check_object: 模型对象，一个 CheckObj 实例, 如：host、mysql等
    :param action: 标识获取的字段类型，在目前场景中只分为：可展示字段、搜索字段两种
    :return:
    * 如果 action 为 None 则同时获取可展示字段和搜索字段，并且返回一个处理(去重)好的 list()
    * 如果传入的在 get_type 中则获取具体的类型, get_type = ['show_field', 'search_field']
    Usage:
    >>> get_fields(check_object)  # 返回所有可展示字段和搜索字段
    >>> get_fields(check_object, action='show_field')   # 返回可展示字段
    """
    pass

python requests 源码中很好的注释:

	# -*- coding: utf-8 -*-

#   __
#  /__)  _  _     _   _ _/   _
# / (   (- (/ (/ (- _)  /  _)
#          /

"""
Requests HTTP Library
~~~~~~~~~~~~~~~~~~~~~

Requests is an HTTP library, written in Python, for human beings.
Basic GET usage:

   >>> import requests
   >>> r = requests.get('https://www.python.org')
   >>> r.status_code
   200
   >>> b'Python is a programming language' in r.content
   True

... or POST:

   >>> payload = dict(key1='value1', key2='value2')
   >>> r = requests.post('https://httpbin.org/post', data=payload)
   >>> print(r.text)
   {
     ...
     "form": {
       "key1": "value1",
       "key2": "value2"
     },
     ...
   }

The other HTTP methods are supported - see `requests.api`. Full documentation
is at <https://requests.readthedocs.io>.

:copyright: (c) 2017 by Kenneth Reitz.
:license: Apache 2.0, see LICENSE for more details.

在必要的地方加上注释

1. 你不怎么理解的代码
2. 别人可能不理解的代码
3. 提醒自己或者别人注意的代码、重要代码
   示例:
   在 if 后面跟很多条件的情况下需要加上注释

   # 是否需要购买
   show_buy_btn = False
   # 满足以下条件则需要购买(lesson 属于 course 、不是免费课程、不是试看课节、未购买过或未领取)
   # 注：lesson 可以不属于 course，这个时候是不存在付费的情形
   if course and not course.is_free and not course.purchase_status and not lesson.is_preview_enabled:
       show_buy_btn = True
   

改换行的换行, 不要写的太紧凑, 阅读起来太困难了。

小结:
在程序中添加注释和文档字符串会让代码具有更好的可读性和维护性。即使以后需要重构代码，因为有注释也会让这个过程变得容易理解很多。
就像这句话说的一样:

Software spends only 10% time of its life in development and rest of 90% in maintenance.

如何"写好"代码?

• 什么是好代码?
  在写代码过程中, 自己实现的那肯定任务自己写的就是好的, 在大多数情况下, 每个人可能都这么认为, 这就很难给好的代码一个定义, 但好代码一定是整洁的, 也是必要的条件, 另外需要可读性强, 无论从风格上或是结构设计上都应该是可读性强的、易维护的。

可读性

好的代码无论是风格、结构还是设计上都应该是可读性很强的。

命名

命名时一个很严肃的事情, 好的名字需要细想斟酌

名副其实

好的名称不需要解释即可明白其含义

足够短

在足够表达含义的情况下越短越好

格式

一块代码逻辑代表一块完整的思路, 不同的代码块中间用空行间隔

类和函数应短小, 更短小

一个函数/类最好不要超过 80 行, 过长的函数一定可读性很差

参数越少越好

参数越多调用越麻烦, 最好是没有, 越多的参数则限制了这个函数的用途, 我们抽象出来是让更多的地方去用

删掉注释的代码

我们使用 git 版本控制, 已经记录了变更历史, 没必要留着

别给糟糕的代码加注释

不解释

参考文献

Google 开源项目风格指南: https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/

python 之禅的代码解读: https://betterprogramming.pub/how-to-make-python-programming-more-elegant-and-decent-4b5962695aa9

Python 之禅

刚开始写代码的时候可能对这些不是很理解, 后续越写越发现 python 之禅里面的解读很到位。

美丽总比丑陋好。
显式优于隐式。
简单胜于复杂。
复杂总比复杂好。
扁平比嵌套好。
稀疏比密集好。
可读性很重要。
特殊情况不足以打破规则。
虽然实用性胜过纯度。
错误永远不应该静默传递。
除非明确沉默。
面对模棱两可，拒绝猜测的诱惑。
应该有一种——最好只有一种——明显的方法来做到这一点。
尽管这种方式起初可能并不明显，除非您是荷兰人。
现在总比没有好。
尽管现在永远不会比*正确*更好。
如果实现很难解释，那是个坏主意。
如果实现很容易解释，这可能是一个好主意。
命名空间是一个很棒的想法——让我们做更多的事情！