From: Craig Maloney Date: Wed, 11 Dec 2019 12:01:12 +0000 (-0500) Subject: More editing in chapter 3 X-Git-Tag: 20200112^2~19 X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=a51f3935a15cfca3afcb455a094aba826a0a49bb;p=themediocreprogrammer.git More editing in chapter 3 --- diff --git a/chapter03.md b/chapter03.md index c6df13b..8d13149 100644 --- a/chapter03.md +++ b/chapter03.md @@ -2,21 +2,21 @@ ## Whoops! -It's bound to happen: something you thought was a good idea didn't work the way you planned and now you realize you've made a terrible error. Sometimes it's something that could have been easily avoided (committing code that was meant for debugging, for instance). Sometimes it's a cascade of errors, each building on the efforts on the previous error. There's the mistake of neglecting the side-effects of a module when it's used in a way that wasn't intended, or it's the realization that you've designed a small, tightly coupled module only to learn that your module will be part of a larger piece of software and your code isn't designed to make a smooth transition. Whoops! +It's bound to happen: something you thought was a good idea didn't work the way you planned, and now you realize you've made a terrible error. Sometimes it's something that could have been easily avoided (committing code that was meant for debugging, for instance). Sometimes it's a cascade of errors, each building on the efforts of the previous error. There's the mistake of neglecting the side-effects of a module when it's used in a way that wasn't intended, or it's the realization that you've designed a small, tightly coupled module only to learn that your module will be part of a larger piece of software and your code isn't designed to make a smooth transition. Whoops! The mistakes that really frighten me though are the ones that I did not expect; the ones where the unintended consequences run rampant throughout the system like a chain-reaction. Those mistakes keep me up at night. -Programmers make mistakes. The nature of our jobs require us to be aware of what is going on in multiple sections of code. We lose track of the state of our program and committed code. We try to pepper our code with comments and reminders of what's going on in a section of code but comments become stale and add to our distraction. We rush and rely on muscle memory to pick up the slack. We deny ourselves areas where we can adequately test code because we feel we need to get things done sooner. +Programmers make mistakes. The nature of our jobs require us to be aware of what is going on in multiple sections of code. We lose track of the state of our program and committed code. We try to pepper our code with comments and reminders of what's going on in a section of code but comments become stale and add to our distraction. We rush and rely on muscle memory to pick up the slack. We deny ourselves areas where we can adequately test code because we feel we need to rush to get things done quickly. We panic, and when we panic we make mistakes. ## Avoiding mistakes -Let's be clear: there's no way to avoid or eliminate mistakes. Software is too complex to be completely bug-freer, but what we can do is create places where we can tease out as many bugs from the code as possible before we set it in front of others. We can better understand our code and what it's doing when we have the ability to debug and test our code in a safe environment. We can see how it will behave under certain circumstances. Creating a model of the target system allows us to test our code against miniaturized versions of the target system's reality and see how it behaves under those conditions. +Let's be clear: there's no way to avoid or eliminate mistakes. Software is too complex to be completely bug-free. What we can do, though, is create places where we can tease out as many bugs from the code as possible before we set it in front of others. We can better understand our code and what it's doing when we have the ability to debug and test our code in a safe environment. We can see how it will behave under certain circumstances. Creating a model of the target system allows us to test our code against miniaturized versions of the target system's reality and see how it behaves under those conditions. -We put a lot of emphasis on avoiding mistakes, both in programming and in programming culture. There are horror stories of how small bugs in a program caused enormous pain for those involved. The moral of these stories illuminate that simple mistakes can be costly and we need to be doubly careful about avoiding mistakes. These anecdotes are told in the hopes that they'll somehow scare developers into being more cautious, but they can have the opposite effect. They can make programmers paranoid about making any mistakes at all, and when we operate in a fear-based mode we begin to panic. Telling programmers to make no mistakes is similar to telling someone not to be afraid: they become more afraid of being afraid. +We put a lot of emphasis on avoiding mistakes, both in programming and in programming culture. There are horror stories of how small bugs in a program caused enormous pain for those involved. The moral of these stories is that simple mistakes can be costly and we need to be doubly careful about avoiding mistakes. These anecdotes are told in the hopes that they'll somehow scare developers into being more cautious, but they can have the opposite effect. They can make programmers paranoid about making any mistakes at all, and when we operate in a fear-based mode we begin to panic. Telling programmers to not make any mistakes is similar to telling someone to not be afraid: they become more afraid of being afraid. -The best (and perhaps only) way we learn is by making mistakes. Learning by making mistakes is an effective way to allow us to be curious and see what caused the program to fail. When we deprive ourselves of the freedom to make mistakes we deprive ourselves of the learning opportunities in making those mistakes. That doesn't mean we have to make every mistake that other developers have made before us (that would be a lot of mistakes). Nor does it mean that we need to introduce chaos into our development process in order to learn better. What it means is that we need to make our own mistakes in our own way in order to keep learning and figure out where the gaps in our understanding exist. +The best (and perhaps only) way we learn is by making mistakes. Learning by making mistakes is an effective way to allow us to be curious and see what caused the program to fail. When we deprive ourselves of the freedom to make mistakes we deprive ourselves of the learning opportunities in making those mistakes. That doesn't mean we have to make every mistake that other developers have made before us (that would be a lot of mistakes). Nor does it mean that we need to introduce chaos into our development process in order to learn better. What it means is that we need to make our own mistakes in our own way in order to keep learning and figuring out where the gaps in our understanding exist. ## Making a model @@ -24,33 +24,33 @@ We need environments where programmers can safely learn from their mistakes. We These environments must model the target systems, and they must be as close as is practical to those target systems. That doesn't mean you need to make exact copies of expensive production environments, but you do need to create models of production environments that test most of the pieces with which your code will come in contact. Having models that mirror production systems means that when you move your code to production you'll introduce fewer changes with unintended consequences. Your changes will have already existed in a production-like environment. You can take comfort in knowing that the changes you enact in these models will be the same changes that will appear on the target system. -Ideally you'll need to have an environment like this on a machine that you control. This means that you're not competing with other programmers in your organization who are also being brave with their changes. But you'll also want to ensure that you keep your environment up-to-date with their changes (and any production changes) so your development model matches what's on the target system and what will be on the target system. A good model is one that is kept current with what it is modeling. It's the same as a map of a city: it's best when it matches the area its modeling and is kept current with changes that occur in that city. A good map of the city might tell you about the recent construction happening on your route. A useless map doesn't even show your route because it wasn't built when the map was created. If our model of production is constantly falling behind what's in production we will spend more time rectifying the changes that we're making with the changes between our model and production. +Ideally you'll need to have an environment like this on a machine that you control. This means that you're not competing with other programmers in your organization who are also being brave with their changes. You'll also want to ensure that your environment is kept up-to-date with their changes (and any production changes) so your development model matches what's on the target system and what will be on the target system. A good model is one that is kept current with what it is modeling. It's the same as a map of a city: it's best when it matches the area its modeling and is kept current with changes that occur in that city. A good map of the city might tell you about the recent construction happening on your route. A useless map doesn't even show your route because it wasn't built when the map was created. If our model of production is constantly falling behind what's in production we will spend more time rectifying the changes that we're making with the changes between our model and production. This also means having an environment that you can rebuild quickly and replicate as needed. Having a model that becomes its own separate reality becomes one more system to maintain. This model should be something that you can delete and rebuild at will in order to remove any previous experiments. It's best to think of it as an ephemeral copy of your target environment that has limited use and can be tossed when no longer necessary. It should be quick to replicate this environment so there's little friction in creating new environments to play in. That can mean scripting the building process for these environments. How you decide to do this is up to you but keep in mind that you want something that's as simple as you can make it and requires as little thought as you can manage to replicate it. -Again, it doesn't have to be perfect - it's only a model, but it does need to be close enough where your code will behave in a similar fashion between the model and the target environment. +Again, it doesn't have to be perfect - it's only a model, but it does need to be close enough so your code will behave in a similar fashion between the model and the target environment. ## Time machines -There are plenty of other folks who will tell you the benefits of revision control (and many folks who will show you the exact steps for how to set up a revision control system). Revision control systems such as `git`, `svn`, `cvs`, and the like have helped programmers coordinate releases and keep a log of what work was added to their project. Having a good revision control system allows you to create areas where you can test code without having to merge these tests into production code. Good revision control lets you to create a space (or "branch" in `git` parlance) based on existing code that you can use to experiment and develop. It also allows you to commit in that space and diverge as much as you want or need to in order to fully explore the changes you're making. What's most important though is that good revision control will also allow you to abandon that space if you need to - you're not forced to add those changes back to your production code. This allows you to see if something might work and abandon those changes if they don't pan out. Good revision control affords the programmers the ability to branch off from any point in time and explore what happened in the code base. In a sense they're time machines and infinite universes, allowing you to play "what if?" scenarios with your code and move back and forward through time in your code. This is vital for your learning because you can feel secure in testing and trying things and are able to rewind those changes (or delete them entirely) without affecting the work of others. +There are plenty of folks who will tell you the benefits of revision control (and many folks who will show you the exact steps for how to set up a revision control system). Revision control systems such as `git`, `svn`, `cvs`, and the like have helped programmers coordinate releases and keep a log of what work was added to their project. Having a good revision control system allows you to create areas where you can test code without having to merge these tests into production code. Good revision control lets you to create a space (or "branch" in `git` parlance) based on existing code that you can use to experiment and develop. It also allows you to commit in that space and diverge as much as you want or need to in order to fully explore the changes you're making. What's most important though is that good revision control will also allow you to abandon that space if you need to -- you're not forced to add those changes back to your production code. This allows you to see if something might work and abandon those changes if they don't. Good revision control affords programmers the ability to branch off from any point in time and explore what happened in the code base. In a sense they're time machines and infinite universes, allowing you to play "what if?" scenarios with your code and move back and forward through time in your code. This is vital for your learning because you can feel secure in testing and trying things and rewinding those changes (or deleting them entirely) without affecting the work of others. Learning how your revision control system works will give you freedom to make mistakes. Many of these systems can seem complex at first, but with continued practice and patience you'll understand what the revision control system is doing and what its capabilities are. You'll be able to judge how many risks you can take with your code and be more confident with the risks you take. -Revision control can also play a role in seeing the development of the code of other folks. You can get a window into their development process and see what certain features look like as they are added. This can help you learn about an unfamiliar code base and can show you the direction they took in order to make the code the way that it is. It can give you a window into the history of a project and what all went into making it happen. Revision control can be a time machine into the history of a project and can help you understand that programming is a process. Not all projects come fully-formed from programmer minds. +Revision control can also play a role in seeing the development of the code of other folks. You can get a window into their development process and see what certain features look like as they are added. This can help you learn about an unfamiliar code base and show you the direction they took in order to make the code the way that it is. It can give you a window into the history of a project and what went into making it happen. Revision control can be a time machine into the history of a project and can help you understand that programming is a process. Not all projects come fully-formed from programmer minds. ## Learning from failure -Sometimes we fail. Sometimes the code we write isn't up to the realities of the system it's implemented on. We push code that does something unexpected and systems break as a result. We can lose track of where we are in our code and make changes that conflict with other changes and causes us to spend the rest of the afternoon undoing those changes. All of these cases cause discomfort, whether to us, the folks we support, or the folks we work with. +Sometimes we fail. Sometimes the code we write isn't up to the realities of the system it's implemented on. We push code that does something unexpected and systems break as a result. We can lose track of where we are in our code and make changes that conflict with other changes which then causes us to spend time undoing those changes. All of these cases cause discomfort, whether to us, the folks we support, or the folks we work with. -I'm not going to lie: failure sucks. It makes us feel like we're less of a person because we failed. We feel inadequate and wonder how others think of us. Do they think less of us? Have we damaged our relationship with those who use whatever we've programmed? Have we let our team down? All of these questions stem from two desires: a desire to do our best and desire to do no harm to others. We want others to think well of us and our skills. Failure runs counter to those desires and amplifies whatever feelings of inadequacy we might have. Those feelings can include wondering if we should be programming at all or wondering if our talents should be used elsewhere. We wonder if we should just give up. +I'm not going to lie: failure sucks. It makes us feel like we're less of a person because we failed. We feel inadequate and wonder how others think of us. Do they think less of us? Have we damaged our relationship with those who use whatever we've programmed? Have we let our team down? All of these questions stem from two desires: the desire to do our best and the desire to do no harm to others. We want others to think well of us and our skills. Failure runs counter to those desires and amplifies whatever feelings of inadequacy we might have. Those feelings can include wondering if we should be programming at all or wondering if our talents should be used elsewhere. We wonder if we should just give up. -We don't usually think of failure as part of the learning process. Failure is often seen as the end-point of the journey. In school a failing grade is seen as a condemnation. We don't see it as "I need to practice this some more"; instead we see that we have caused shame and discomfort to ourselves and our loved ones. We do ourselves a grave disservice if we don't realize that failure is a natural part of the learning process and that it's OK to fail. Not everything we do will be perfect. Mistakes will creep into the best code we write. We will slip up and deploy to the wrong system. Our mistakes will cause discomfort to others. Accepting this gives us the freedom to realize that despite our best efforts we will not be perfect. Instead of seeing that as a limitation we can use failure as part of our growth process. +We don't usually think of failure as part of the learning process. Failure is often seen as the end-point of the journey. In school a failing grade is viewed as a condemnation. We don't view it as "I need to practice this some more"; instead we feel that we have caused shame and discomfort to ourselves and our loved ones. We do ourselves a grave disservice if we don't realize that failure is a natural part of the learning process and that it's OK to fail. Not everything we do will be perfect. Mistakes will creep into the best code we write. We will slip up and deploy to the wrong system. Our mistakes will cause discomfort to others. Accepting this gives us the freedom to realize that despite our best efforts we will not be perfect. Instead of viewing failure as a limitation we can use it as part of our growth process. When we realize we are going to make mistakes we can change our approach in how and where we make them. I mentioned before about creating models of our environments. What better way to allow us to make mistakes than in an environment where those mistakes can be contained and rolled back? Creating models allows us to practice and test our assumptions in environments that nobody else has to see. It's akin to a practice space for musicians where they can run through their material without the need to perform it right the first time. They can work out the troublesome parts and make mistakes until they are confident in their performance. -Mistakes are how we learn what works and what doesn't work. They are an integral part of our learning process. We tend to remember the lessons of what didn't work better than the ones that did work. Mistakes help us shore up where we lack knowledge and help us see the gaps that we have. +Mistakes are how we learn what works and what doesn't work. They are an integral part of our learning process. We tend to remember the lessons of what didn't work better than the ones that did work. Mistakes help us shore up where we lack knowledge and help us understand the gaps we've yet to close. -Mistakes also act as a reminder to pause for a moment and not get too wound up in the urgency of things. My own mistakes tend to crop up when I'm rushing to meet a deadline (whether real or self-imposed). My worst mistakes happen when I'm tired and rushed, when I'm practically flailing at the keyboard trying to get something (anything!) working. When I allow myself to pause for a moment, reflect on what I'm trying to do, and see the uncertainty in the moment I can take steps to recalibrate and refocus in the moment. I give myself the freedom to course-correct and understand that I'm not doing my best and I need to do something different. It might be something small like giving my brain a bit of rest or something large like revisiting the assumptions I made about what I'm doing. Taking the pause lets me see if I want to continue doing what I'm doing and understand if that's OK. +Mistakes also act as a reminder to pause for a moment and not get too wound up in the urgency of things. My own mistakes tend to crop up when I'm rushing to meet a deadline (whether real or self-imposed). My worst mistakes happen when I'm tired and rushed, when I'm practically flailing at the keyboard trying to get something (anything!) working. When I allow myself to pause for a moment, reflect on what I'm trying to do, and feel the uncertainty in the moment I can take steps to recalibrate and refocus in the moment. I give myself the freedom to course-correct and understand that I'm not doing my best and need to do something different. It might be something small like giving my brain a bit of rest or something large like revisiting the assumptions I made about what I'm doing. Taking the pause lets me determine if I want to continue doing what I'm doing and understand if that's the best path. ## Journaling our mistakes