CODEWITHSUNDEEP
pythoncomments
Vor
Vor

Reputation: 35129

What is the proper way to comment code in Python?

I was reading PEP8 and some questions on Stack Overflow, but I was wondering about spaces between comments:

Let’s say I have this code:

class MyBrowser(QWebPage):
    ''' Settings for the browser.'''

    def __init__(self):
        QWebPage.__init__(self)
        # Specifies whether images are automatically loaded in web pages.
        self.settings().setAttribute(QWebSettings.AutoLoadImages, True)

    def userAgentForUrl(self, url):
        ''' Returns a User Agent that will be seen by the website. '''
        return "Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.15 (KHTML, like Gecko) Chrome/24.0.1295.0 Safari/537.15"

What is the most Pythonic way of putting blank lines between comments and the actual code? I want to show my program to some experts. And want my code to look more professional.

Upvotes: 6

Views: 23754

Answers (4)

Raymond Hettinger
Raymond Hettinger

Reputation: 226346

When in doubt, look at the standard library for a model.

Here's an excerpt from the timeit module (written by Guido van Rossum himself):

def print_exc(self, file=None):
    """Helper to print a traceback from the timed code.

    Typical use:

        t = Timer(...)       # outside the try/except
        try:
            t.timeit(...)    # or t.repeat(...)
        except:
            t.print_exc()

    The advantage over the standard traceback is that source lines
    in the compiled template will be displayed.

    The optional file argument directs where the traceback is
    sent; it defaults to sys.stderr.
    """
    import linecache, traceback
    if self.src is not None:
        linecache.cache[dummy_src_name] = (len(self.src),
                                           None,
                                           self.src.split("\n"),
                                           dummy_src_name)
    # else the source is already stored somewhere else

    traceback.print_exc(file=file)

Upvotes: 3

droid192
droid192

Reputation: 2232

Instead of giving snippets, look at the most used CPython using sphinx and compare the doc to the code.

The documentation are never out of sync since the annotations sit right inside the code.

Upvotes: 0

Jason Sperske
Jason Sperske

Reputation: 30426

I don't know if this represents the "community standard" but here are Google's Python style guides (as they relate to comments). Specifically classes:

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Upvotes: 16

brian buck
brian buck

Reputation: 3454

From the Zen of Python: "Readability counts." Whatever your team finds to be most readable is what I would do.

Upvotes: 1

Related Questions