...
The following sections contain more specific tips on what to do or not do when it comes to variable naming accuracy overall.
Don’t Use Overly Short Variable Names
| Status | ||||
|---|---|---|---|---|
|
Consider the following code. Can you guess what the meanings of these variables are or what the code is even doing?
...
:
...
Don’t Use Unrelated Variable Names
| Status | ||||
|---|---|---|---|---|
|
It’s possible to use longer variable names that are off-topic or unrelated to what the variables represent. Such names might be fun, but they muddy the waters in trying to get a reader to understand the code.
The following shows how unrelated variable names can be problematic and revised to be better:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"5252c226-01e5-487c-8ff2-4fc95ac40059","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int MY_DOGS_FAVORITE_NUMBER = 65;\nconst bool x_marks_the_spot = (user_age_in_years > MY_DOGS_FAVORITE_NUMBER);\nif (x_marks_the_spot)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int RETIREMENT_AGE_IN_YEARS = 65;\nconst bool user_over_retirement_age = (user_age_in_years > RETIREMENT_AGE_IN_YEARS);\nif (user_over_retirement_age)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"8d6effdb-ac22-434d-8314-2a3d266d730b","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint MyDogsFavoriteNumber = 65;\nbool xMarksTheSpot = (userAgeInYears > MyDogsFavoriteNumber);\nif (xMarksTheSpot)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint RetirementAgeInYears = 65;\nbool userOverRetirementAge = (userAgeInYears > RetirementAgeInYears);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"d31bf11c-3232-4073-96e1-1b7fa64e1fce","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int MY_DOGS_FAVORITE_NUMBER = 65;\nboolean xMarksTheSpot = (userAgeInYears > MY_DOGS_FAVORITE_NUMBER);\nif (xMarksTheSpot)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int RETIREMENT_AGE_IN_YEARS = 65;\nboolean userOverRetirementAge = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"b96f5b30-a4b1-4c40-b8b7-7ce0f20e53a5","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"MY_DOGS_FAVORITE_NUMBER: int = 65\nx_marks_the_spot: bool = user_age_in_years > MY_DOGS_FAVORITE_NUMBER\nif x_marks_the_spot:\n # Do something..."}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"RETIREMENT_AGE_IN_YEARS: int = 65\nuser_over_retirement_age: bool = user_age_in_years > RETIREMENT_AGE_IN_YEARS\nif user_over_retirement_age:\n # Do something..."}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"e7bfdda0-a7cc-4010-82e4-b194cffc60e7","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const MY_DOGS_FAVORITE_NUMBER = 65;\nlet xMarksTheSpot = (userAgeInYears > MY_DOGS_FAVORITE_NUMBER);\nif (xMarksTheSpot)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userOverRetirementAge = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"379e5d8c-42e0-41a0-8a72-cad524ffa8ec","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Variable names unrelated to the problem at hand. The code seems to be mixing different concepts such that it just doesn’t make much sense. Even if "},{"type":"text","text":"some","marks":[{"type":"em"}]},{"type":"text","text":" of the variable names might be correct, it’s hard to tell what the intent of the code is."}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const MY_DOGS_FAVORITE_NUMBER: number = 65;\nlet xMarksTheSpot: boolean = (userAgeInYears > MY_DOGS_FAVORITE_NUMBER);\nif (xMarksTheSpot)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"Improving the names: ","marks":[{"type":"strong"}]},{"type":"text","text":"Better variable names communicate more accurately what the code is trying to do:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS: number = 65;\nlet userOverRetirementAge: boolean = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
Double-Check Variable Name Accuracy
| Status | ||||
|---|---|---|---|---|
|
It’s always good to double-check accuracy of your variable names. If code looks more correct, a reader might more confidently think the code is correct, and inaccurate variable names can be misleading. Consider the following example:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"aebcc771-82cb-4633-b5d6-3af720d9fe45","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int RETIREMENT_AGE_IN_YEARS = 65;\nconst bool user_under_retirement_age = (user_age_in_years > RETIREMENT_AGE_IN_YEARS);\nif (user_under_retirement_age)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"user_under_retirement_age","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"user_over_retirement_age","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int RETIREMENT_AGE_IN_YEARS = 65;\nconst bool user_over_retirement_age = (user_age_in_years > RETIREMENT_AGE_IN_YEARS);\nif (user_over_retirement_age)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"943ff042-f07c-411e-aab0-27ffd8a5c3a3","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint RetirementAgeInYears = 65;\nbool userUnderRetirementAge = (userAgeInYears < RetirementAgeInYears);\nif (userUnderRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"userUnderRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"userOverRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint RetirementAgeInYears = 65;\nbool userOverRetirementAge = (userAgeInYears > RetirementAgeInYears);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"1d3e6caa-885c-4fa6-ae77-405358ce20b0","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int RETIREMENT_AGE_IN_YEARS = 65;\nboolean userUnderRetirementAge = (userAgeInYears < RETIREMENT_AGE_IN_YEARS);\nif (userUnderRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"userUnderRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"userOverRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int RETIREMENT_AGE_IN_YEARS = 65;\nboolean userOverRetirementAge = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"2ef1e7eb-2157-4be4-8e6a-345122a4be0a","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"RETIREMENT_AGE_IN_YEARS: int = 65\nuser_under_retirement_age: bool = user_age_in_years < RETIREMENT_AGE_IN_YEARS\nif user_under_retirement_age:\n # Do something..."}]},{"type":"paragraph","content":[{"type":"text","text":"user_under_retirement_age","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"user_over_retirement_age","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"RETIREMENT_AGE_IN_YEARS: int = 65\nuser_over_retirement_age: bool = user_age_in_years > RETIREMENT_AGE_IN_YEARS\nif user_over_retirement_age:\n # Do something..."}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"43d8866d-8daf-4b19-b1f4-ef1423819fa1","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userUnderRetirementAge = (userAgeInYears < RETIREMENT_AGE_IN_YEARS);\nif (userUnderRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"userUnderRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"userOverRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userOverRetirementAge = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"9ea747a7-6c44-45e2-b5c2-a291222451d6","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code:","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS: number = 65;\nlet userUnderRetirementAge: boolean = (userAgeInYears < RETIREMENT_AGE_IN_YEARS);\nif (userUnderRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"userUnderRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" is inaccurate for this code example - the boolean expression is checking if a user is over the retirement age. With an inaccurate variable name, a user quickly glancing over the code could think the logic in the "},{"type":"text","text":"if","marks":[{"type":"code"}]},{"type":"text","text":" block is in response to a user actually being "},{"type":"text","text":"under","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age, when what the code will actually be doing there is in response to a user being "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" the retirement age. Inaccurate variable names like this are a recipe for subtle bugs that can be tricky to find and debug."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the variable name: ","marks":[{"type":"strong"}]},{"type":"text","text":"The name should be "},{"type":"text","text":"userOverRetirementAge","marks":[{"type":"code"}]},{"type":"text","text":" in this case:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS: number = 65;\nlet userOverRetirementAge: boolean = (userAgeInYears > RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
Precisely Identify Boundary Conditions
| Status | ||||
|---|---|---|---|---|
|
Related to the previous tip, exercise care in naming when boundary conditions are involved. See the example below:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"ee3c2d58-bd21-4ace-a27c-05f4989a2e14","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int RETIREMENT_AGE_IN_YEARS = 65;\nconst bool user_over_retirement_age = (user_age_in_years >= RETIREMENT_AGE_IN_YEARS);\nif (user_over_retirement_age)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr unsigned int RETIREMENT_AGE_IN_YEARS = 65;\nconst bool user_reached_retirement = (user_age_in_years >= RETIREMENT_AGE_IN_YEARS);\nif (user_reached_retirement)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"52e15ba0-3baf-4880-b214-5e88e784997c","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint RetirementAgeInYears = 65;\nbool userOverRetirementAge = (userAgeInYears >= RetirementAgeInYears);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const uint RetirementAgeInYears = 65;\nbool userReachedRetirement = (userAgeInYears >= RetirementAgeInYears);\nif (userReachedRetirement)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"dcddd0e1-fa82-4433-9270-086d280d3749","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int RETIREMENT_AGE_IN_YEARS = 65;\nboolean userOverRetirementAge = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final int RETIREMENT_AGE_IN_YEARS = 65;\nboolean userReachedRetirement = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userReachedRetirement)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"57d4b676-454d-4808-8420-2f11763f9b89","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"RETIREMENT_AGE_IN_YEARS: int = 65\nuser_over_retirement_age: bool = user_age_in_years >= RETIREMENT_AGE_IN_YEARS\nif user_over_retirement_age:\n # Do something..."}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"RETIREMENT_AGE_IN_YEARS: int = 65\nuser_reached_retirement: bool = user_age_in_years >= RETIREMENT_AGE_IN_YEARS\nif user_reached_retirement:\n # Do something..."}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"47afc63e-bae3-4c62-a96d-2c1b6b125d6a","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userOverRetirementAge = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userReachedRetirement = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userReachedRetirement)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"63e97327-71f8-410f-8a95-b28c3b22824a","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"Can you identify any bugs in this code snippet?"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS: number = 65;\nlet userOverRetirementAge: boolean = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userOverRetirementAge)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[{"type":"text","text":"The boolean seems to be checking if the user is "},{"type":"text","text":"over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than) the retirement age, but the actual comparison is checking if the user is "},{"type":"text","text":"at-or-over","marks":[{"type":"em"}]},{"type":"text","text":" (greater-than-or-equal-to) the retirement age."}]},{"type":"paragraph","content":[{"type":"text","text":"Correcting the code: ","marks":[{"type":"strong"}]},{"type":"text","text":"It’s possible that either the variable name or comparison in the boolean expression is inaccurate. If the comparison is inaccurate, it should be fixed. But assuming the comparison is what is intended, then best to improve the boolean variable name to precisely identify the condition:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const RETIREMENT_AGE_IN_YEARS = 65;\nlet userReachedRetirement = (userAgeInYears >= RETIREMENT_AGE_IN_YEARS);\nif (userReachedRetirement)\n{\n // Do something...\n}"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
A program might need to do different things depending on if a user is exactly the retirement age, is older than the specific retirement age, or has reached the retirement age at all. You want the resulting logic to be correct - and for readers to correctly understand the logic - so make sure such boundary conditions are precisely identified in your variable names.
Include the Primary “What” in the Variable Name
| Status | ||||
|---|---|---|---|---|
|
A key aspect of variable naming accuracy is including the primary “what” in the variable name for what the variable represents. Variables typically will represent some kind of “noun.” Make sure you don’t leave that information out of the variable name when naming it.
Consider the following code:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"6beb2758-cabe-4575-b7b3-cf26b2c25522","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"ExecutableProgram runnable_on_linux = GetProgram(executable_path);"}]},{"type":"paragraph","content":[{"type":"text","text":"From the data type assigned to this variable, it looks like this variable is for some kind of “executable program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnable_on_linux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"ExecutableProgram linux_program = GetProgram(executable_path);"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"bd6bd755-3ffd-4cc0-8657-fe132035a30e","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"ExecutableProgram runnableOnLinux = GetProgram(executablePath);"}]},{"type":"paragraph","content":[{"type":"text","text":"From the data type assigned to this variable, it looks like this variable is for some kind of “executable program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnableOnLinux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"ExecutableProgram linuxProgram = GetProgram(executablePath);"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"aec743a9-ddd6-4855-b107-6089fd5f121d","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"ExecutableProgram runnableOnLinux = getProgram(executablePath);"}]},{"type":"paragraph","content":[{"type":"text","text":"From the data type assigned to this variable, it looks like this variable is for some kind of “executable program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnableOnLinux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"ExecutableProgram linuxProgram = getProgram(executablePath);"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"0815c6f4-53b6-4503-b980-f0ef904c88f6","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"runnable_on_linux: ExecutableProgram = get_program(executable_path)"}]},{"type":"paragraph","content":[{"type":"text","text":"From the data type assigned to this variable, it looks like this variable is for some kind of “executable program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnable_on_linux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"linux_program: ExecutableProgram = get_program(executable_path)"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"ea755adf-2916-4749-a8c3-20cb2facee41","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"let runnableOnLinux = getProgram(executablePath);"}]},{"type":"paragraph","content":[{"type":"text","text":"From the function called whose return value assigned to this variable, it looks like this variable is for some kind of “program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnableOnLinux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"let linuxProgram = getProgram(executablePath);"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"78e307b1-5b65-4c32-a9e0-12552b3b1962","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Original code: ","marks":[{"type":"strong"}]},{"type":"text","text":"A variable lacking the primary “what” in its name:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"let runnableOnLinux: ExecutableProgram = getProgram(executablePath);"}]},{"type":"paragraph","content":[{"type":"text","text":"From the data type assigned to this variable, it looks like this variable is for some kind of “executable program” object. However, that information isn’t evident from the "},{"type":"text","text":"runnableOnLinux","marks":[{"type":"code"}]},{"type":"text","text":" variable name itself - that variable name looks like it might be a boolean, and there’s no real indication in the variable name itself of exactly “what” is runnable on Linux."}]},{"type":"paragraph","content":[{"type":"text","text":"Revising the name: ","marks":[{"type":"strong"}]},{"type":"text","text":"You’d want to at least include the primary noun (“program”) in the variable name. That makes it much clearer “what” the primary thing the variable holds is:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"let linuxProgram: ExecutableProgram = getProgram(executablePath);"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
Distinguish Between Singular and Plural Data
| Status | ||||
|---|---|---|---|---|
|
It is common for code to operate on both singular and plural data - “one” instance of an item or “multiple” instances of an item. There can be big differences in the two that are important for maintenance programmers to be aware of.
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"9b2aec22-4867-4601-a82c-55ce44fec8ea","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"const std::string WORD_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"const std::string ONE_OR_MULTIPLE_WORDS_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"8216fb48-7d14-494b-928f-8d99665581ab","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const string WordRegex = \"\\\\w+\";"}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const string OneOrMultipleWordsRegex = \"\\\\w+\";"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"5791c18c-92b4-4b45-8281-82b487778345","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final String WORD_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final String ONE_OR_MULTIPLE_WORDS_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"0065bcbc-7908-47ff-ac4f-845769aeb04d","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"WORD_REGEX: str = r\"\\w+\""}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"ONE_OR_MULTIPLE_WORDS_REGEX: str = r\"\\w+\""}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"7fbea657-a644-442a-a6c4-9d154fb05629","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const WORD_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const ONE_OR_MULTIPLE_WORDS_REGEX = \"\\\\w+\";"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"25ca911c-0995-4d46-98fd-62590c26184a","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Consider the following regex variable:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const WORD_REGEX: string = \"\\\\w+\";"}]},{"type":"paragraph","content":[{"type":"text","text":"\\w","marks":[{"type":"code"}]},{"type":"text","text":" is intended to match a single word, but the "},{"type":"text","text":"+","marks":[{"type":"code"}]},{"type":"text","text":" at the end indicates that multiple words can be matched. That would be best clarified in the variable name so that someone using the variable recognizes that multiple words could potentially be matched:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const ONE_OR_MULTIPLE_WORDS_REGEX: string = \"\\\\w+\";"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
Distinguish Between Different Kinds of “Fractional” Numbers
| Status | ||||
|---|---|---|---|---|
|
There are many different kinds of “fractional” numbers - numbers representing less than a “whole” in some way - that can appear in code. Because they can have different implications, it’s important to distinguish between them.
“Decimal” is sometimes used to communicate a number that may have digits after a decimal point. Such terminology should be avoided since it more accurately refers just to the decimal number system and could cause confusion.
The following terms can be useful to distinguish between other kinds of fractional numbers:
Percent or percentage - Reserve these terms for numbers than can range from 0 to 100 (unless true percentages outside that range are expected). People most intuitively understand percentages to be in the range of 0 to 100, so to label a variable as a
percentwould lead to an expectation of that variable holding the value45for 45% (not0.45).Fraction, proportion, or ratio - These terms are best used when the value of the number is actually less than a whole number (or may have fractional components greater than a whole number - ex.
1.24). Exactly which term is best depends on context, though “fraction” tends to be more suitable for values truly less than a whole number, whereas “proportion” or “ratio” can be more intuitively applicable to numbers greater than 1.
Making these distinctions accurately is important for correctness in a codebase. If a number is already a percentage, it shouldn’t need to be multiplied by 100 to make it a percentage - such a multiplication would throw off the value of a variable. For example:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"45fcc947-2656-4950-94ba-66520c6abfdf","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr double PERCENTAGE_POINTS_PER_WHOLE = 100.0;\ndouble progress_percent_for_display = progress_percent * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"constexpr double PERCENTAGE_POINTS_PER_WHOLE = 100.0;\ndouble progress_percent_for_display = progress_proportion * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"98316182-6468-4830-aa60-4505427e5b34","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const double PercentagePointsPerWhole = 100.0;\ndouble progressPercentForDisplay = progressPercent * PercentagePointsPerWhole;"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"const double PercentagePointsPerWhole = 100.0;\ndouble progressPercentForDisplay = progressProportion * PercentagePointsPerWhole;"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"3f6a155b-427b-459a-8396-94506766364e","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final double PERCENTAGE_POINTS_PER_WHOLE = 100.0;\ndouble progressPercentForDisplay = progressPercent * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"final double PERCENTAGE_POINTS_PER_WHOLE = 100.0;\ndouble progressPercentForDisplay = progressProportion * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"23952239-ef46-46bb-982d-5204d781209c","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"PERCENTAGE_POINTS_PER_WHOLE: float = 100.0\nprogress_percent_for_display: float = progress_percent * PERCENTAGE_POINTS_PER_WHOLE"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"PERCENTAGE_POINTS_PER_WHOLE: float = 100.0\nprogress_percent_for_display: float = progress_proportion * PERCENTAGE_POINTS_PER_WHOLE"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"dddc32ec-fdbc-4646-a8b6-74ea0796a0ec","value":"JavaScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const PERCENTAGE_POINTS_PER_WHOLE = 100.0;\nlet progressPercentForDisplay = progressPercent * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"type":"text","text":"const PercentagePointsPerWhole = 100.0;\nlet progressPercentForDisplay = progressProportion * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"d5a2210c-a1c3-44eb-8c0b-b97e9d2698a3","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"This looks suspiciously incorrect as a percentage is being multiple by 100:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const PERCENTAGE_POINTS_PER_WHOLE: number = 100.0;\nlet progressPercentForDisplay: number = progressPercent * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[{"type":"text","text":"If the "},{"type":"text","text":"progress_percent","marks":[{"type":"code"}]},{"type":"text","text":" variable name is accurate, then the multiplication should just be removed. But if that variable holds a value between 0 and 1, then the variable name itself should be changed:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"const PERCENTAGE_POINTS_PER_WHOLE: number = 100.0;\nlet progressPercentForDisplay: number = progressProportion * PERCENTAGE_POINTS_PER_WHOLE;"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
If you’re working in a highly mathematical codebase, you may need to make more precise distinctions between different kinds of numbers.
Fully Represent Multi-Part Values in Variables
| Status | ||||
|---|---|---|---|---|
|
Many programming languages have evolved to allow storing “multiple” values in variables via things like “pairs” or “tuples.” When this occurs, make sure to fully represent these values in variable names.
Consider the following code:
| Navitabs tab wizard |
|---|
{"type":"custom","custom":{"tabs":[{"id":"6f070f83-2a9c-4f56-a62f-ecea91fa869b","value":"C++","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"The called function seems to return a pair of values, but the variable name is just car. It’s not clear what the other value in the pair, the string, might be:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"std::pair<std::string, Car> car = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[{"type":"text","text":"A better variable name can help clarify - it captures the meaning of both parts of the pair in an order that mimics the order of actual values in the pair:"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"type":"text","text":"std::pair<std::string, Car> manufacturer_name_and_car = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"72c3c5d9-d30c-4671-bd9f-d5135fceb4c1","value":"C#","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"The called function seems to return a pair of values, but the variable name is just car. It’s not clear what the other value in the pair, the string, might be:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"Tuple<string, Car> car = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[{"type":"text","text":"A better variable name can help clarify - it captures the meaning of both parts of the pair in an order that mimics the order of actual values in the pair:"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"type":"text","text":"Tuple<string, Car> manufacturerNameAndCar = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"86b80a49-b86f-47b7-b321-06906e643f62","value":"Java","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"The called function seems to return a pair of values, but the variable name is just car. It’s not clear what the other value in the pair, the string, might be:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"Pair<String, Car> car = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[{"type":"text","text":"A better variable name can help clarify - it captures the meaning of both parts of the pair in an order that mimics the order of actual values in the pair:"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"type":"text","text":"Pair<String, Car> manufacturerNameAndCar = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"eb9afea3-7f39-4772-beb1-23f518bf54ad","value":"Python","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"The called function seems to return a pair of values, but the variable name is just car. It’s not clear what the other value in the pair, the string, might be:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"car: Tuple[str, Car] = LookupCar(\"Civic\")"}]},{"type":"paragraph","content":[{"type":"text","text":"A better variable name can help clarify - it captures the meaning of both parts of the pair in an order that mimics the order of actual values in the pair:"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"manufacturer_name_and_car: Tuple[str, Car] = LookupCar(\"Civic\")"}]},{"type":"paragraph","content":[]}]},"type":"your-content"},{"id":"04bda109-72b5-45c5-86a9-c19c48856c38","value":"TypeScript","body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"The called function seems to return a pair of values, but the variable name is just car. It’s not clear what the other value in the pair, the string, might be:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"let car: [string, Car] = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[{"type":"text","text":"A better variable name can help clarify - it captures the meaning of both parts of the pair in an order that mimics the order of actual values in the pair:"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"type":"text","text":"let manufacturerNameAndCar: [string, Car] = LookupCar(\"Civic\");"}]},{"type":"paragraph","content":[]}]},"type":"your-content"}],"design":null,"minHeight":0,"vertical":false,"isEmbedded":false}} |
If you have a variable that is a tuple with many values, trying to name them all may result in a name that is too long to be practical. In such a case, you might be able to find a suitable higher-level abstraction for the variable name, but you have to be careful - another programmer still needs to be able to use all of the values in a tuple. Redesigning the code - potentially by creating a custom data type with well-named fields for each value in the tuple - may be a better solution.
Name At the Right Level of Abstraction
| Status | ||||
|---|---|---|---|---|
|
You generally want to name in the problem domain as much as possible. However, code for any non-trivial program will have multiple levels of abstraction. Ensure your names are at the right level of abstraction for the code you are working in.
For example, the file_handle name below seems like it’s at an inappropriate level of abstraction based on the data type for the variable (a higher-level “file” object):
| Code Block | ||
|---|---|---|
| ||
File file_handle("path/to/file"); |
The name should just be file in this case:
| Code Block | ||
|---|---|---|
| ||
File file("path/to/file"); |
Now, within the File class, you might need to go down a level of abstraction and thus have to deal with actual “file handles.” In such a case, a name with “handle” would be appropriate to provide distinction between the different levels of abstraction:
...
| language | cpp |
|---|
...
| Child pages | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|