Formatting methods and functions with trailing parentheses in instructor text

[wflynny]

Throughout much of the Python 3 documentation and PEP8 style guide, functions and methods are referenced in code blocks with trailing parentheses, as function() and .method(), respectively. I think this is extremely helpful in showing new (and experienced) users that the object of interest is callable, i.e. not an attribute, a keyword, flow control statement, etc., and pointing new users to the object (function, method) could lead to subtle misunderstanding.

Currently in all of the episodes of this lesson, functions and methods do not have trailing parentheses, and introducing this function/method formatting to this lesson would be valuable to the students IMO. For example, the instruction text in Episode 4 "Built-in Functions and Help" starts as:

A function may take zero or more arguments.

• We have seen some functions already — now let’s take a closer look.
• An argument is a value passed into a function.
• len takes exactly one.
• int, str, and float create a new value from an existing one.
• print takes zero or more.
• print with no arguments prints a blank line.
  • Must always use parentheses, even if they’re empty, so that Python knows a function is being called.

By formatting functions with trailing parentheses, this becomes:

A function may take zero or more arguments.

• We have seen some functions already — now let’s take a closer look.
• An argument is a value passed into a function.
• len() takes exactly one.
• int(), str(), and float() create a new value from an existing one.
• print() takes zero or more.
• print() with no arguments prints a blank line.
  • Must always use parentheses, even if they’re empty, so that Python knows a function is being called.

While I think this makes formatting clearer for the majority of the instruction text, there are some potential pitfalls. For example,

from math import cos, pi

print("cos(pi) is", cos(pi))

It might be confusing to new users to then reference the cosine function used above as cos() in subsequent instructor text. Maybe it warrants more distinction between the function object cos and the function being called cos() than the short bullet at the beginning of the episode.

I wanted to ask for feedback on this idea before I opened a PR.

[vahtras]

Dear Bill, Thank you for your suggestion. I can sort of see your point, but I don't think your suggestion makes the text clearer for new students. It is important to be able talk about names for function objects both with and without parentheses, and understanding the difference, in my opinion.

Regards, Olav