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))

「何をすべきか」に焦点を当てているだけで、他には何も説明していません。もっと良い方法があると思いますが、自分で良い方法を考えるのではなく、賢者の知恵が欲しいです。

スタイル ガイド PEPを読んだことがありますが、これは役に立ちますが、「英語を書くときは、Strunk と White を適用する」よりも少し詳しく、大規模で複雑な python プロジェクトのコメント作成者の知恵を引き出すものが必要です。.

4

3 に答える 3

2

関数のドキュメント化はdocstringで行う必要があります。関数の上のあなたのコメントは私には理解できません。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

直接的な答えではありませんが、質問に関連していると思います。

Steve McConnell は、影響力のある著書Code Completeの中で、最初に達成したいことを説明する粗い疑似コードを書き、問題領域の単語 (たとえば、「CustomerRecords のリスト」ではなく「顧客」) を使用することを提唱しています。次に、「コードをさらに洗練するよりも、コードを書くだけの方が簡単に感じる」まで、疑似コードを改良します (記憶から言い換えます)。

ここで、疑似コードをコメントアウトし、疑似コードの各行の下に実際のコードを入力します。疑似コードはそのままにしておきます。これは、コードの意図を説明するコメントとして非常にうまく機能するようになったためです。

于 2013-04-21T08:16:12.933 に答える