파이썬 코드를 어떻게 주석해야합니까?

Question

오픈 소스 나 "전문적인"파이썬 코드 (예 : webapp2 또는 webob)에서 주석이 많이 보입니다. 의견은 코드보다 많습니다. 나는 개인 개발자도 자신의 애플 리케이션 에서이 일을 발견했습니다. 커다란 간격, 많은 댓글, 그리고 몇 줄의 코드가 자주 있습니다.

나는이 스타일이 마음에 든다고 생각한다. 그리고 이제는 파이썬에서 더 큰 프로젝트입니다. 코드와 커멘트로 커다란 프로젝트를 구성해야 할지도 모릅니다. 더 읽기 쉽고 유지 보수가 잘 될뿐만 아니라 더 나은 코더를 만들 수 있다고 생각합니다. 일이 더 명확해질 것이기 때문입니다.

그냥 생각해 보니 코드 검토에서이 질문이 더 좋은가요? 듣고는

은 현재 난 그냥 예를 들어, 다음과 같이 의견을 순종하는 것입니다 단지 "수행 할 작업"하지만 아무 것도 설명하지 않습니다에 집중한다

#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 쓰는 영어, 스 트렁크와 화이트 "보다 좀 더 자세하게 큰 복잡한 파이썬 프로젝트을 걸러내어 뭔가 적용 "이 필요합니다.

Answer 1

직접적인 대답은 아니지만 질문과 관련이 있다고 생각합니다. 자신의 독창적 인 책 코드 전체에서

스티브 맥코넬 먼저 설명 거친 의사를 서면으로 옹호 당신이 (예를 들어, "고객"대신 "CustomerRecords의 목록"의) 문제의 도메인에서 단어를 사용하여 수행 할 작업. 그런 다음 의사 코드를 수정하여 "코드를 작성하여 메모리를 더 많이 사용하는 것이 더 쉽다"고 말할 때까지 수정하십시오.

지금 의사 코드를 주석과 의사의 각 라인 아래에있는 실제 코드를 입력하고, 그것이 어디 지금 코드의 의도을 설명하는 주석으로 아주 멋지게 역할로, 의사 코드를 둡니다.

Answer 2

면책 조항 : 저는 현자가 아닙니다.

파이썬은 매우 읽기 쉽습니다.하지만 보통은 가독성을 떨어 뜨리는 간격이없는 것을 보았습니다. 주로 간격/주석을 사용하여 코드의 구조를 보여 주며, 까다로운 코드 블록을 설명하기 위해 간혹 사용합니다. 후자의 경우, 일반적으로 코드를 재구성하는 것이 더 좋습니다. 긴 문서를 탐색하는 대신 가능하면 덜 까다롭게 만듭니다.

Google의 프로그래밍 전문 지식을 고려할 때 일반적으로 Python Style Guide (Comments)이 좋은 리소스입니다.

Answer 3

기능을 문서화하려면 docstring이어야합니다. 함수 위에있는 귀하의 의견은 나를 위해 이해할 수 없습니다. 문서화 문자열은 다음과 같이 수 : 코드가 무엇, 효과적으로 복제 그들은 단지 decribe 때문에 코드에서

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: 
     ... 

인라인 의견은 매우 도움이되지 않습니다.

대신에 을 사용하는 이유는 즉시 명확하지 않은 경우 코드가 어떤 작업을하는지 설명합니다.