Commit shell files¶
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.
Write in-line comments¶
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
With the right tests, you can convince yourself that parts of your code are correct, and that allows you to concentrate your debugging efforts.
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...
Mysterious names and magic numbers: variables have names which don’t indicate their function
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.
My somewhat controversial advice is to keep IO, long-running pipelines, and functions and classes out of jupyter notebooks.
totally agree with this! might be worth mentioning somewhere that Jupyter notebooks play badly with version control...
. black imposes consistent Python style, and has plugins for all the popular IDEs.
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).
You have two options, change your Python path, or create an installable package. I recommend the installable package route, but cover the Python path route first because you’re likely to encounter it in other projects.
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)
Trust Game
5 mm