我应该如何评论python代码？

我经常在开源或“专业”python代码中看到注释 - 比如webapp2或webob，看起来非常分散。评论似乎超过了代码。我注意到个别开发人员也在自己的应用程序中执行此操作。大的间距，大量的评论，然后每隔几行代码几行代码。我应该如何评论python代码？

我想我喜欢这种风格，它感觉更有组织。现在，我是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的读 - 这是有帮助的，但一些评论提炼的智慧auteurs与不是“写英语时，斯特伦克和白色的更详细一点的大复杂的Python项目申请“是必需的。

来源

2013-04-21 Cris Stringfellow

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

在他的重要著作代码大全，史蒂夫·麦康奈尔主张首先编写粗糙的伪代码解释你要完成的，用字从问题域（例如的“客户”，而不是“CustomerRecords的名单”）什么。然后对伪代码进行细化，直到“编写代码比编写代码更容易”（从内存释义）。

现在注释掉伪代码和伪代码的每一行下面的实际代码填写，并留下伪它在哪里，因为它是现在非常漂亮充当解释代码的意图评论。

来源

2013-04-21 08:16:12

是的，我认为这就像我的目标，作为我的战略之一，以解决更大的项目。谢谢！ – 2013-04-21 08:18:02

声明：我不是一个圣人。

Python本身非常易读，但我通常看到缺少可读性的间距。我主要使用间距/注释来显示代码中的结构，偶尔用于解释棘手的代码块。对于后一种情况，重构代码通常会更好，如果可能的话，这样做不那么棘手，而不是深入研究长文档。

鉴于谷歌的编程专业知识，他们的Python Style Guide (Comments)通常是一个很好的资源。

来源

2013-04-21 08:20:18 fgb

记录该功能应该在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-21 09:59:20

我应该如何评论python代码？

回答

相关问题