├── README.md └── images ├── junk-drawer.png └── signal-to-noise.png /README.md: -------------------------------------------------------------------------------- 1 | # Sustainable Coding 2 | 3 | > We are what we repeatedly do. Excellence, then, is not an act but a habit. - Aristotle 4 | 5 | This document describes my ever-evolving perspective on the strive for excellence as a software developer. Its focus is on writing code, more than code itself. Even though creation and the thing created are intimately related, I consider improvements made in a software developer's mindset to be more important than improvements made in a source code file. 6 | 7 | I chose the title 'Sustainable Coding' to reflect this ambition. Here's why… 8 | 9 | **Sustainable** 10 | 11 | Despite the current buzzword status of *sustainable* I could not find a better adjective to describe my objective. Two definitions of [sustainable](http://www.oxforddictionaries.com/us/definition/american_english/sustainable) from Oxford Dictionary are: 12 | - Able to be maintained at a certain rate or level 13 | - Able to be upheld or defended 14 | 15 | These definitions provide the raw material for a professional software developer's creed: 16 | 17 | > I develop high-quality software that can be maintained at a reliable rate, using only practices which I am willing to uphold and defend. 18 | 19 | **Coding** 20 | 21 | I chose *coding* instead of *code* as the second word of the title to emphasize my focus on writing code more than the code that is written. It might be a subtle distinction, but it is an important one. 22 | 23 | ## APE 24 | When working on something, resist the temptation to jump directly into writing or changing code. 25 | 26 | It is important to Assess, Plan, and Execute (APE). 27 | 28 | - Assess the requirements, problems, unknowns, etc. 29 | - Plan how to implement the work that needs to be done, based on your assessment. 30 | - Execute your plan. 31 | 32 | > The first casualty of any battle is the plan of attack. - Cory Doctorow 33 | 34 | It's common to go back to assessment or planning as new facts are uncovered. 35 | 36 | ## Fixing bugs 37 | Give each bug fix its due diligence, otherwise your fix will likely create more bugs. 38 | 39 | Fix the problem, not a symptom. 40 | 41 | Decide how to fix a bug only once you understand what causes it. 42 | 43 | If you can't explain why your fix works, it is not a valid fix. 44 | 45 | ## Writing for the reader 46 | ### Readability 47 | Code should be written so that it is easy to read. 48 | 49 | The easier code is to read, the less difficult it is to maintain and extend. 50 | 51 | A subjective measure of how easily code can be read is called "readability." 52 | 53 | Consistently applied code formatting and naming conventions improve readability. 54 | 55 | The choice of particular formatting and naming conventions is far less important than their consistent usage. 56 | 57 | ### Signal-to-noise ratio 58 | 59 | ![Signal in the noise](/images/signal-to-noise.png) 60 | 61 | An empty source code file has no "visual noise." 62 | 63 | Every character of text added to a file increases its visual noise. 64 | 65 | The developer's intent is a "signal" which someone reading the code discovers in the visual noise. 66 | 67 | Maximizing readability involves finding a signal-to-noise "ratio" that conveys your intent, without obscuring it with too little or too much text. 68 | 69 | For example, a local variable that is only used in a short block of code should not have a long name. Similarly, the name of a function or class used by other modules should not be terse or abbreviated. 70 | 71 | Another way to improve the signal-to-noise ratio is to ensure that every character of text is necessary. A line of code that is unnecessary, or unnecessarily complicated, increases the amount of visual noise while decreasing the signal strength. 72 | 73 | ## Choosing names 74 | ### Call it what it is 75 | The name of a thing determines what you think that thing is. 76 | 77 | A poorly chosen name distorts your understanding of what a thing is. 78 | 79 | When understanding is distorted by a name, a "mental mapping" is needed to bridge the gap. 80 | 81 | Mental mappings increase the reader's cognitive burden, thereby decreasing their ability to effectively work with and improve the codebase. 82 | 83 | Rename something if its role/purpose changes. Don't stick with the old name because you happen to know what it currently means. Other developers (including Future You) will need to spend time and energy creating a mental mapping. 84 | 85 | ### Select your words as carefully as a lawyer 86 | A name should make it clear what something is or does, not how it is implemented. 87 | - Prefer: `findHighestPaidEmployee()` 88 | - Avoid: `selectFirstEmployeeFromListSortedBySalary()` 89 | 90 | Specific, accurate names have better explanatory power: 91 | - Prefer: `authenticateUserIfRequiredAfterProlongedInactivity()` 92 | - Avoid: `authenticateUserIfRequiredByTheRules()` 93 | 94 | Suppose you need to write a method that modifies a customer's `Priority` based on a `Status` field. 95 | - Good name: `adjustCustomerPriorityBasedOnStatus()` 96 | - Poor name: `makeCustomerPriorityMatchStatus()` 97 | - Rationale: The customer's `Priority` and `Status` fields are related but not equivalent or *matching*. Therefore, the word "match" in the second example is inappropriate and misleading. 98 | 99 | ### Avoid creating junk drawers 100 | ![Junk drawer](images/junk-drawer.png) 101 | 102 | Vague class names, like `SessionManager` or `DataController`, should be avoided because such classes tend to become a junk drawer whose existence discourages developers from critically analyzing where to put new code. 103 | 104 | Junk drawer classes are large, disjointed, and complicated. This makes them difficult to understand and fix. 105 | 106 | As more and more code accumulates in a junk drawer, it becomes difficult to *not* put new code into it, because it contains so many things that need to be referenced. 107 | 108 | ## Improving code in a business workplace 109 | > It's easier to ask forgiveness than it is to get permission. - Grace Hopper 110 | 111 | Code can, and should, be improved. 112 | 113 | Improvements can be categorized as "external" or "internal." 114 | 115 | External improvements increase the value of software for users. 116 | 117 | Internal improvements increase the livability of a project for developers. 118 | 119 | Fixing a bug is a type of external improvement. 120 | 121 | Removing knowledge duplication is a type of internal improvement. 122 | 123 | In a business workplace, internal improvements sometimes must be made "under the radar" because non-developers seldom appreciate the importance of changes that have no immediate impact on scheduled deliverables. 124 | 125 | As a professional software developer it is your duty to make frequent, minor internal improvements to a codebase, despite the opinions of non-technical managers unqualified to appreciate the psychological benefits such changes can have for developers. 126 | 127 | A professional software developer should not, nor should be required to, ask management for permission to make minor internal improvements. 128 | 129 | On the other hand, it is unprofessional to covertly spend a lot of time making broad, sweeping changes in order to implement an internal improvement. Such changes can introduce unnecessary risk and take too much time away from making business-critical external improvements. 130 | 131 | Strike a balance between doing what your employer tells you is necessary and doing what you know is best for your team, based on your expertise as a professional software developer. 132 | 133 | --- 134 | 135 | *This is a continual work-in-progress. More to come…* 136 | -------------------------------------------------------------------------------- /images/junk-drawer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ijoshsmith/sustainable-coding/27c9962025e137127cbdd43a2828d397b64cd74c/images/junk-drawer.png -------------------------------------------------------------------------------- /images/signal-to-noise.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ijoshsmith/sustainable-coding/27c9962025e137127cbdd43a2828d397b64cd74c/images/signal-to-noise.png --------------------------------------------------------------------------------