Basics notes

[parthsarin]

1. Style guide violations

Explanations in Code

The style guide specifies that we should not have explanations in code. You do this once, in the file reading section:

file_text = f.read(size) # Reads size bytes from the file; if size is omitted, the entire file is read.
first_line = f.readline() # Reads the file one line at a time.
all_lines = f.readlines() # Returns a list with all lines of the file.

Printed Output

The style guide specifies

When an expression will result in printed terminal output, this should be written after the expression and a blank line. Each line of output should be commented out with the hash sign at the beginning of the line, a space, and then the terminal output. The implication sign should not be included.

But many of your examples use the implication sign to offset printed output, like

print("I'm dancing.")              # => I'm dancing.
print('"This is fun!" he cried.')  # => "This is fun!"

Maybe remove the print statements or convert the implication comments to print-style comments?

Italics

You frequently use italics to denote terms when they're introduced.

Nitpicky Spacing

You're using two spaces instead of one in many of the return value implicatures

math.gcd(45, 105)  # => 15
math.cos(3.14)     # => -0.9999987317275395
math.cos(math.pi)  # => -1.0

I know this is very nitpicky but... let's be consistent?

2. File I/O with open/close

You wrote

It's almost always a better idea to use the paradigm of the context manager when performing File I/O in Python. Cases where it is superior to use the open/close paradiem are significantly fewer - only use it if you have a clear, good reason to do so.

I'm curious: can you think of any time where it's superior to use the open/close paradigm?

Reading Bytes

f.read(size) reads size many bytes only when the file is open in bytes mode and size many characters otherwise.

3. C-Style Formatting

Why are we showing them C-style formatting at all if we immediately move on to say "never do this"?

Also, this code is incorrect:

print("{0} then {1} then {0} then {1} then {0}." % ("Parth", "Michael"))  # => Parth then Michael then Parth then Michael then Parth

4. Add Filenames

When a file is introduced, I think we should add filenames at the top to make it clear that this is happening inside a file.

"""
File: hello.py
--------------
"""
...

5. Revisit the Signature

Let's have a consistent signature.

[cooper-mj]

1. Style guide violations

Explanations in Code

I agree with the overall principle of no explanations in code, but I can't help but thinking that there's a better way for introducing a collection of functions en-masse than what the style guide would seem to imply (which is that they be introduced one after the other in a progressive narrative format, with one-line code blocks containing sample code sprinkled throughout). I'll do more thinking on this.

Printed Output

See this pull request.

Italics

These will be switched to quotes in my next revision.

Nitpicky Spacing

...

2. File I/O with open/close

I can't currently - but I'm generally hesitant to use words like always and never since I want to leave open the possibility of a compelling case that I haven't yet thought of.

Reading Bytes

Noted - will update in my next revision.

3. C-Style Formatting

We're introducing it for this reason (from the style guide):

These notes are not a guide on how to use Python so they should generally avoid walking the reader through an implementation. That will happen in class. Instead, these notes will should explain Python's language design and philosophy.

Think "this is how Python does X" instead of "here's how to do X in Python."

C-consistency with formatting seems important when discussing how Python does string formatting - it calls back to the history of the language, and the paradigms with which early Python programmers would have been most familiar. Just because students - and most programmers, probably - nowadays would be more comfortable with the format syntax or with f-strings doesn't mean that this isn't another neat milestone in the timeline of Python's string formatting developments.

Re: the erroneous line - noted and fixed.

4. Add Filenames

Good idea - I'll add to the style guide.

5. Revisit the Signature

Agree - I'll add to the style guide.

[parthsarin]

1. Let's revisit in person.
2. Okay, then can we at least more strongly condemn using the open/close paradigm because if an error occurs it can leave the file open?
3. I agree with your counter-point!
4. Great.
5. Great/revisit in person.