this reads like a recommendation of this pattern, which I would disagree with. Makefiles are a much better option - in particular because they stop when they hit an error (unless you tell them to do otherwise). I personally would recommend against this and in favor of a Make-like process.

I'd personally like to see a bit more editorializing here on commenting. so many people think that commenting is the sine qua non of readable code. I like the bob martin quote: “Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments” (Robert Martin, Clean Code)

also - if you want to give a reference somewhere on these issues, I think that The Art of Readable Code is a great book that hits these issues with a minimum of complexity

I really like this quote from Martin Fowler: “Whenever you are tempted to type something into a print statement or a debugger expression, write it as a test instead.” might be worth suggesting this kind of approach...

not sure I agree with this - I think they should be listed separately as they are really separate things. when I think of magic numbers, I think of numbers embedded in code directly (e.g. foo = j * 1250 - what the hell is 1250?) so they are not actually variables at that point - they are constants. and I think both are so important that it's worth calling out each of them separately.

totally agree with this! might be worth mentioning somewhere that Jupyter notebooks play badly with version control...

might mention that this can be really useful for bringing older code up to current standards, even if you don't use it in your regular workflow (which I don't - I just use flake8).

I'm not sure that this level of detail is necessary, but it could be worth discussing somewhere how this interacts with the development process - i.e. one would never want to use dynamic changes in the sys.path once the package is developed, but if one is developing a module while using it in a separate piece of code, then having to reinstall via pip each time is a bit of a pain. I think you should at least mention below that one needs to add -U to upgrade the package if it's already installed (unless you have bumped the version # in the setup.py file, at least I think that's true)

5 mm