The pragmatic programmer | Insights, and thoughts part 4
Hello reader and welcome to the fourth part of this series where we talk a little about the many insights I got from a book I've read recently: “The pragmatic programmer”, as I said in the previous episodes, certainly a lot of things changed since 1999 when the book(and me too) were published, but the insights remained timeless and valuable as always.
In a certain part of the book, the authors mention a phenomenon called:
Programming by coincidence
More than never we are using code, we as programmers use libs, open-source stuff, vendors solutions, boilerplate code and that's valuable and makes our productivity increase, but the problem is when we don't know exactly how it works and what every line of code in our source code means and does. Because we end up assuming the code works and that it works magically, and that's not attractive if we got bugs or scalability problems we have lines of code that we don't know what it does so how are we supposed to optimize and solve bugs in code that we don't understand, and if we got this pattern of magic code all over our source code we are programming by coincidence just because we don't know what's going on the execution of the program. I see it as a very hard temptation to resist especially in more mainstream languages like node.js because it's so easy to install a lib on npm that solves the problem, but every lib installs another huge amount of libs and so on and so on that, it's hard to keep up knowing what every lib is doing, so normally I only try to know what the libs I installed in my package JSON are doing and assume the dependencies of my dependencies are ok and abstracted because just by doing it I make sure I'm not programming by coincidence on my direct dependencies, and it saves me time, and mental health. But stay aware that for every line of code you put on your project you really understand what it is doing and make sure that you are not programming by coincidence.
So next time something seems to work, but you don’t know why, make sure it isn’t just a coincidence.
Source code control
The authors also mention that in their opinions all stuff should be under source control, even if you are the only one working on the project, because of the safety that your code will not get deleted if your hard drive gets destroyed, but also for collaboration reasons that it's easy to manage contributions, and it gives a time machine to your source code. The only part I don't completely agree with is when they mention that not only code should be under source control but presentations, pdfs, images, 3d models, and .psds files, I think if your project is small you will get no problem doing it but if your project gets bigger with PSD files containing hundreds of megabytes you will notice that tools like git will get slow into encoding, decoding and keeping track of such large files and the solutions for this problem is to configure your source code system by telling them you are going to use intensive media, so the system will keep track of it in a more optimized algorithm for this type of file, or the easiest in my opinion that is to use a file manager to store your media files like dropbox, google drive, one drive, etc., they were made to store and keep files and the most part of them have free plans, of course the authors don't mention this option on the book because in 1999 there were no file storage on the cloud, or cloud, and the internet was still a newborn like me.
Documentation
Documenting software is hard that's why tech writers must be valued, and that's why we should collaborate with them, but in a project, without tech writers, the responsibility of good documentation remains on the architects and developers and some tips of the writers to create good documentation are:
— Keep it updated
— Keep it on the web
— Try to connect a documentation tool with your source code so whenever you update your code it creates an updated version of the documentation of that endpoint our source file
Documentations is quite a responsability, and you cant put every single detail in specification, because some things will depend on human interpretation
Imports by alphabetical order
This one will depend on the tools you are using and in the team you are working on, but when I read it I got an insight that I never thought much about the order of my imports before I normally used to import things in a way that it was easy to not get lost or by copying the way other developers did the imports if the project was a commercial project but was nice to see a different way of seeing the same stuff from the point of view of the authors.
Here we are at the end of one more episode of this almost odyssey, as I said in previous episodes the book gave me a lot of interesting insights, so I'm writing them all down, and I hope you like them as much I enjoyed reading such a timeless book.