Author here. A friend mentioned this was on the front page so I wanted to stop by and make explicit that this advice is OUT OF DATE as far as I'm concerned. It's way too much hassle (I work in a much larger team now than I did then!) and doesn't play well with rebase etc.
These days I either recommend the jupytext approach (not tried it but seems sensible) or personally I just use Sphinx-gallery.
Advantages:
* Plain python files play well with IDE refactoring, Black formatter, etc etc.
* You now have a readymade 'tutorial' page for your docs.
* Files are run with every docs build, so you can configure things to alert you when they're broken.
Disadvantages:
* You end up editing a throwaway notebook file. If you forget to copy-paste your edits back to the source, and rebuild, you have lost your edits. However, this forces me to keep the 'temporary, exploratory' nature at the front of my mind and not allow the notebook code to grow too large before performing some clean-up.
Things are changing, slowly but surely. Those of you interested in this sort of work should check out http://rse.ac.uk/, and also https://software-carpentry.org/ (Run a workshop! Improve the software environment around you!)
I don't really understand this persistent "carpentry/craftsman" analogy - it seems to me software dev isn't really like a craft at all. I'd sooner stick to "software engineering".
But it isn't engineering. Not really. The number of things you can measure and plan for in advance of implementation are much, much smaller than the number of things you need to build every day. Engineering is a discipline with thousands of years of practice and study behind it, and the traditional 'best practice' is far more likely to work than ones from the programming world. What's more, once the plans have been written, implementation, even prototyping, are predictable and tend to proceed apace. Engineers do not guess, and they test much less than we do, because unless they're working on the bleeding edge, the results are a forgone conclusion for all but the most intricate constructs.
In programming, the map is the territory, and in the time you can map out and nail down all of the unpredictable bits of a program, you could have written it already. We also don't have the luxury of physical laws. The few natural laws that do apply, the speed of light and time complexity, are so rarified and remote that they don't apply most of the time. We share more with the mathematician than the engineer, but even that comparison rings hollow.
We create programs custom built for a purpose, using rules of thumb and our own aesthetic instincts, that meet a need. Craftsman seems appropriate.
It's true that software differs from many Physical Engineering practices too, but why does this automatically make "craft" appropriate? Are Mathematicians called craftsmen because there is no physical output to their efforts?
> We create programs custom built for a purpose, using rules of thumb and our own aesthetic instincts
Software can be general too, it's not the same as, say, making a small stool or chair. Plus, craftsmen are tied to physical constraints too, much like engineers. I'm not sure I agree with how much s/w depends on "rules of thumb and our own aesthetic instincts" though.
This is something I've been giving some thought to recently. I came to the conclusion that the best way to go currently is git-clean filters built using jq. It's still a bit hacky though. Gentle write-up here: http://timstaley.co.uk/posts/making-git-and-jupyter-notebook...
While I see what you're saying, I doubt you would claim to 'use' assembly when writing a C++ codebase - because (unless you're doing very low-level hand optimizations of the kind that get ever rarer), someone else has done the hard work of creating a compiler to do the translation for you. Same thing with NumPy et al, except one level higher up the abstraction stack.
Actually, that's precisely what I do, except it's called machine language, not assembly. That is because assembly is an intermediate format above machine language (it's symbolic).
Interesting dilemma. I had assumed that re-writing in another language basically meant you were copyright free (as long as you're not literally transcribing or automatically translating), but it appears it's not that simple: http://imranontech.com/2006/12/04/are-algorithms-copyrightab...
It'll be a bit more expensive than your local store, but you could try ordering (decaf) beans online. Weirdly this seems to be a much bigger thing over here in the UK, but I did find this: http://dailygrind.com/index.php?cPath=22_27
Author here. A friend mentioned this was on the front page so I wanted to stop by and make explicit that this advice is OUT OF DATE as far as I'm concerned. It's way too much hassle (I work in a much larger team now than I did then!) and doesn't play well with rebase etc.
These days I either recommend the jupytext approach (not tried it but seems sensible) or personally I just use Sphinx-gallery.
Advantages:
* Plain python files play well with IDE refactoring, Black formatter, etc etc.
* You now have a readymade 'tutorial' page for your docs.
* Files are run with every docs build, so you can configure things to alert you when they're broken.
Disadvantages:
* You end up editing a throwaway notebook file. If you forget to copy-paste your edits back to the source, and rebuild, you have lost your edits. However, this forces me to keep the 'temporary, exploratory' nature at the front of my mind and not allow the notebook code to grow too large before performing some clean-up.