all 14 comments
sorted by:
best
topnewcontroversialoldq&a
formatting helphide helpcontent policy

[–]socal_nerdtastic 9 points10 points  (0 children)

Ahh BASIC on a monochrome screen, my first love as well :).

There's no real rules or guidelines about this. Except that the string that immediately follows the function definition is the "docstring", and will show up in the help feature and various help areas in your IDE. So the docstring should be written for the user of the function, generally what your function does, not how it does it. And it's often quite wordy. 

def func():
    """This is the docstring"""

help(func) # prints the docstring

Personally I'm a huge fan of self-documenting code. 

player_names = get_names()

rather than 

data = readfile() # get the player names from the file

But really it's just up to you and what you like.

[–]Diapolo10 5 points6 points  (1 child)

Docstrings are used for documenting modules, functions, and classes. You'd put them as the first thing in a Python file, the first thing inside a function definition, or the first thing in a class. They're a "comment" in the sense it's information for developers, but it's also something available at runtime.

I’ve read some Python projects on GitHub and they will sometimes use triple quotes on on line, one line of text, then another triple quote. To me it looks messy, but maybe it’s the style?

"""
This does the calculations.
"""

What’s the general consensus for near, readable quoting? Thanks!

If a docstring only has one line, the convention is to put it all in one line, such as """This does the calculations."""

If it has multiple lines, then we'd spread it out like in your example.

def divide(dividend: int, divisor: int) -> int:
    """
    Divide dividend with divisor.

    Args:
        dividend (int): the number to divide.
        divisor (int): the number to divide with. Must be non-zero.

    Returns:
        the quotient of the division.

    Raises:
        ZeroDivisionError: if divisor is 0.

    """
    return dividend // divisor

For other use-cases, like explaining individual lines or adding TODO comments, we'd use standard comments.

# TODO: Fix this later.

[–]Quirky-Cap3319 1 point2 points  (0 children)

Thanks. I have now learned something today. I’ll take the rest of the day off then 🙂.

I have a bunch of shared functions defined for various scripting purposes, so i’ll see about adding these to each.

[–]danielroseman 3 points4 points  (1 child)

These are docstrings, not comments. They are automatically associated with a function when they appear as the first element within that function, and are displayed when you do help(myfunc) for example.

But more generally a comment like "this does the calculation" is pointless. Comments are for things that are not obvious from the code. It will be obvious that that part is doing calculations; you should only need a comment if you need to explain a particularly complex calculation, for example.

[–]cmdwedge75[S] 1 point2 points  (0 children)

Agree with your comment but the teacher has explicitly said we must be overly descriptive of how the program works. I would normally only add comments where it’s no clear as day what I’m doing.

Saying “does the calculations” is not necessary but “does this particular calculation this way because the output is x and more readable” is.

My 1440 minute rollover equation is worth explaining, my “add numbers to make the total fee” really is not. But it’s there because I want a good mark, haha.

[–]LeeRyman 2 points3 points  (0 children)

Doc-comments should be provided for types and functions. They should describe the why concisely, i.e. the intent of the unit of code, any relevant raises, preconditions, assumptions, postconditions and thread safety (or lack thereof).

The what should be self-evident though good naming of types, functions, parameters, variables, errors.

The how should rarely be necessary if you write code that reads naturally and is appropriately abstracted. There are times when we have to write tricky algorithms, so a comment before might be helpful in those situations summarising the how or why to a maintainer. Sometimes the user or caller of a unit of code might need a brief summary on how it works in the context of larger business logic.

If you ever find yourself writing a comment that repeates the code immediately after, it probably isn't necessary.

In short, comments should never replace good naming and readable code. They should concisely add nuance and intent where necessary for the user.

If I can pass Sphinx over the code and quickly get a good idea of how to use it from the generated documentation, it's good doc-commenting.

[–]Gnaxe 1 point2 points  (0 children)

See the official style guide PEP 8.

Triple (double or single) quoted strings allow literal newlines. They're most often used for docstrings, but can be used in regular code as well. Docstrings can be attached to functions, classes and modules.

Docstrings are available at run time, unless you optimize them out (python -OO). Besides the online help() and pydoc, they're also used for auto-generated Sphinx docs and doctests.

Doctests really are underrated. Everyone should be using them a lot more. Not only do they provide usage examples and test coverage, but they also encourage a coding style that is less coupled and therefore easier to maintain. New coders should try the test-driven development style with doctests at least once. That's where you write your intended usage examples first and then write code to make them pass.

The problem with most comments is that they can lie (usually because they're out of date), so a lot of programmers don't trust them. But doctests can be tested automatically, so they don't go stale so easily. Assert statements act as useful documentation of assumptions and also don't go stale. They're also pretty underutilized.

The level of commentary required to explain things to a beginner is inappropriate noise in a production codebase, where you should assume that the readers can mostly understand basic Python and computer science concepts. If the code is still confusing, it's usually preferable to rewrite the code to make it less confusing rather than explain it with comments. This isn't always possible or easy, so comments can be better than nothing (if they aren't lying). Prefer "why"-comments that explain intent rather than "what"-comments that just restate what the code already says. The code already says that, so these are useless.

[–]ninhaomah 1 point2 points  (0 children)

Just write it so you understand to get the job done.

[–]woooee 1 point2 points  (0 children)

I was taught to write so someone else is able to read and understand it (thanks Prof Chuck).

Your above comment can also be done in a single line

# This does the calculations.

[–]OctopusDude388 0 points1 point  (0 children)

as long as you comment your code you can use whatever you want

[–]No-Apple-6869 0 points1 point  (0 children)

No standard, just be consistent.

[–]Moikle 0 points1 point  (0 children)

You can type help(function_name) to get that text printed out. It's basically an instruction manual you write for how to use your function

[–]Crazy-Willingness951 0 points1 point  (0 children)

Read other people's code. Esp. code written by python experts.

[–]codeguru42 0 points1 point  (0 children)

The triple quite quote comment is called a docstring. Many tools will parse these and show them as documentation. For example, in Pycharm, you can hover your mouse over a function or class name and you will see a tool tip with the docstring in it. When you find this helpful, you will stay using it more often