| | 66 | ---- |
| | 67 | Finally, since this is the best tip that you can have when coding, I included this ''must-read'' article from makinggoodsoftware.com directly here: |
| | 68 | |
| | 69 | ==== 1. The variable name has to be as descriptive as possible. Don´t use generic names. ==== |
| | 70 | |
| | 71 | Good example: daysDateRange, flightNumber, carColor. |
| | 72 | |
| | 73 | Bad example: days, dRange, temp, data, aux… |
| | 74 | |
| | 75 | There are a lot of developers who would prioritize short variable names over descriptive names because that will save time when typing the code, but who cares? It doesn’t help to improve the quality of the software, it only saves a few minutes per day (maximum) per developer, by the other hand, when having descriptive variable names, the overall quality of the software will increase because it will be easier to modify and read the code. |
| | 76 | |
| | 77 | ==== 2. The variable name has to be as short as possible. ==== |
| | 78 | |
| | 79 | This rule goes hand by hand with the first rule, the variable names should be as short as possible but as descriptive as possible. |
| | 80 | |
| | 81 | This basically means that while we still try to come up with short names, we prioritize descriptive names over short names, we only pick the shorter one when they are as descriptive as the longer one. |
| | 82 | |
| | 83 | Bad Examples: howLonDoesItTakeToOpenTheDoor, howBigIsTheMaterial... |
| | 84 | |
| | 85 | Good Examples: timeToOpenTheDoor, !MaterialSize. |
| | 86 | |
| | 87 | ==== 3. It´s OK to use abbreviations, but explain the abbreviation with a comment. ==== |
| | 88 | |
| | 89 | Sometimes to have a good descriptive name is necessary to make very long variable names, which is fine, but the variable size can be improved by using abbreviations, just make sure that when the variable is declared there’s a comment that explains the meaning. |
| | 90 | |
| | 91 | ==== 4. Use proper Hungarian notation when necessary. ==== |
| | 92 | |
| | 93 | There’s a great post from Joel on software that explains what the proper Hungarian notation is and how to use it. Basically it says that when coding a method where we have variables holding the same data, but with different types, the Hungarian notation can help us. |
| | 94 | |
| | 95 | Example: Imagine a method that receives apples, then it classifies the apples depending in their color, and finally discards the ones that are not matured enough. We could use in this example the following variable names: incoming_apples, red_apples, yellow_apples, notMaturedYellow_apples, red_apples, maturedGreen_apples... |
| | 96 | |
| | 97 | ==== 5. Don´t use negative logic for your variable names. ==== |
| | 98 | |
| | 99 | Good Example: !IsEnabled. |
| | 100 | |
| | 101 | Bad Example: !IsNotEnabled. |
| | 102 | |
| | 103 | It’s always easier to read and undertand an statement that is expressed in a positive language that in a negative language. |
| | 104 | |
| | 105 | ==== 6. Be consistent. ==== |
| | 106 | |
| | 107 | If you have used a variable name called customer in a method, then don’t call it client in the next method, or if you use an abbreviation in one method, use it for all the methods the same. |
| | 108 | |
| | 109 | ==== 7. Map the application domain terminology with your names. ==== |
| | 110 | |
| | 111 | In different domains, different concepts have very specific and different meanings, for example, “order” doesn’t always mean the same in the different domains, try to map these specific concepts with your variable names so that when you name something with a concept from the business domain it means exactly the same. |
| | 112 | |
| | 113 | Example. If your customer just considers “order” an “order” that has been approved, don’t call “order” to a non approved one in your code, call it “nonApprovedOrder”. |
| | 114 | |
| | 115 | ==== Golden rule. Spend a few minutes thinking about your variable names. ==== |
| | 116 | |
| | 117 | If you find yourself writing variable names as soon as you need them in your code without even thinking on their name for a second, you are probably picking bad names for them. |
| | 118 | |
| | 119 | If you always try to have good variable names, and you have found yourself thinking a couple of minutes for the best name for a variable, even if you don’t follow the other tips, you are likely to have pretty good variable names in your code. |
| | 120 | |
| | 121 | ---- |
| | 122 | |
