0

我经常在开源或“专业”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))

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

我已经阅读了Style Guide PEP——它很有帮助，但是对于大型复杂的 python 项目来说，提炼评论作者的智慧的东西比“写英语时，Strunk and White apply”更详细一点是必需的.

4

3 回答 3

5

免责声明：我不是圣人。

Python 本身可读性很强，但我经常看到缺少间距会降低其可读性。我主要使用间距/注释来显示代码中的结构，偶尔用于解释棘手的代码块。对于后一种情况，通常最好重组代码，尽可能减少复杂性，而不是深入研究冗长的文档。

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

于 2013-04-21T08:20:18.700 回答
2

记录函数应该在docstring中完成。您对函数的评论对我来说是不可理解的。文档字符串可能如下所示：

def patch(s,*a,**k):
    """Patch a ...

    Arguments:
    s - A ... object
    Any additional arguments are handed to s.resolve().

    Returns:
    bla

    Raises:
    ValuesError when s is not ...
    """
    s.resolve(*a,**k)
    for mod in s.requested_modifications:
        ...

代码中的内联注释不是很有帮助，因为它们只描述了代码的作用，有效地复制了它。

相反，使用注释确实描述了为什么代码在不立即显而易见的情况下会做某事。

于 2013-04-21T09:59:20.710 回答
1

不是直接的答案，但我觉得它与问题有关。

在他的开创性著作Code Complete中，Steve McConnell 提倡首先编写粗略的伪代码来解释您想要完成的任务，使用来自问题领域的词语（例如“客户”而不是“客户记录列表”）。然后细化伪代码，直到“感觉只写代码比细化它更容易”（从记忆中解释）。

现在注释掉伪代码并在每行伪代码下面填写真实代码，并将伪代码留在原处，因为它现在可以很好地用作解释代码意图的注释。

于 2013-04-21T08:16:12.933 回答