我应该如何评论python代码？

Question

我经常看到开源或“专业”python 代码中的注释——比如 webapp2 或 webob，看起来很间隔。评论似乎超过了代码。我注意到个别开发人员也在他们自己的应用程序中这样做。大间距，大量注释，然后是每隔一段时间写几行代码。

我想我喜欢这种风格，它确实感觉更有条理。现在我是用 python 做的更大的项目，我想知道我是否应该像我看到其他人所做的那样，用代码和注释来组织一个大项目。我认为这可能会使它更具可读性和可维护性，并且可能使我成为一个更好的编码员——因为事情会更清楚。

只是想：这个问题在代码审查上更好吗？听就是服从

目前我只是这样评论，例如：

    #U - Idempotent. b-atching requests 
    # which can be PUT, DELETE or GET. 
    #@control.access.collector_or_owner        
    def patch(s,*a,**k):
            s.resolve(*a,**k)
            for mod in s.requested_modifications:
                    method = mod.get('method') or 'PUT'
                    point = s.current_point+mod.get('point') or ''
                    body = mod.get('body') or ''
                    s.say('Will execute %s on %s for %s\n' % (method,point,body))
                    # create the in-app request
                    mod_request = webapp2.Request.blank(point)
                    mod_request.body = str(body)
                    mod_request.method = method
                    mod_request.app = s.app
                    # then find the handler and report
                    execute_tuple = s.app.router.match(mod_request)
                    mod_request.route,mod_request.route_args,mod_request.route_kwargs = execute_tuple
                    handler = mod_request.route.handler
                    if handler not in s.app.router.handlers:
                            s.app.router.handlers[handler] = handler = webapp2.import_string(handler)
                    else:
                            handler = s.app.router.handlers[handler]
                    s.say('Will execute %s on %s for %s via %s\n' % (method,point,body,execute_tuple))
                    # then execute
                    in_app_response = webapp2.Response()
                    handler = handler(mod_request,in_app_response)
                    handler.dispatch() 
                    s.say('Response is %s\n' % (in_app_response))

它只关注“要做什么”，但没有解释其他任何事情。我确信有更好的方法，但与其想出我自己的更好方法，我还需要圣人的智慧。

我已经有一个读风格指南PEP -这是有帮助的，但蒸馏出一些评论的智慧auteurs需要用比“写英语时，斯特伦克和白色的应用”更多的细节大复杂的Python项目.

Answer 1

免责声明：我不是圣人。

Python 本身具有很强的可读性，但我通常看到缺少间距会降低其可读性。我主要使用间距/注释来显示代码中的结构，偶尔用于解释棘手的代码块。对于后一种情况，重构代码通常会更好，如果可能，使其不那么棘手，而不是钻研冗长的文档。

鉴于 Google 的编程专业知识，他们的Python 风格指南（评论）通常是一个很好的资源。