{"id":3654,"date":"2017-09-24T05:00:53","date_gmt":"2017-09-24T05:00:53","guid":{"rendered":"http:\/\/www.nikola-breznjak.com\/blog\/?p=3654"},"modified":"2017-09-05T23:16:53","modified_gmt":"2017-09-05T23:16:53","slug":"code-complete-2-steve-mcconnell-power-variable-names","status":"publish","type":"post","link":"https:\/\/nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-power-variable-names\/","title":{"rendered":"Code Complete 2 \u2013 Steve McConnell \u2013 The Power of Variable Names"},"content":{"rendered":"<p>I just love Steve McConnell&#8217;s classic book <a href=\"http:\/\/amzn.to\/2vdwv5v\">Code Complete 2<\/a>, and I recommend it to everyone in the Software &#8216;world&#8217; who&#8217;s willing to progress and sharpen his skills.<\/p>\n<p>Other blog posts in this series:<\/p>\n<ul>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-part-1-laying-foundation\/\">Part 1 (Chapters 1 &#8211; 4): Laying the Foundation<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-design-construction\/\">Chapter 5: Design in Construction<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-working-classes\/\">Chapter 6: Working Classes<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-high-quality-routines\/\">Chapter 7: High-Quality Routines<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-defensive-programming\/\">Chapter 8: Defensive programming<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-pseudocode-programming-process\/\">Chapter 9: Pseudocode Programming Process<\/a><\/li>\n<li><a href=\"http:\/\/www.nikola-breznjak.com\/blog\/books\/programming\/code-complete-2-steve-mcconnell-general-issues-using-variables\/\">Chapter 10: General Issues in Using Variables<\/a><\/li>\n<\/ul>\n<h3>The Most Important Naming Consideration<\/h3>\n<p>The name must fully and accurately describe the entity that the variable represents. Names should be as specific as possible. Names like <code>x<\/code>, <code>temp<\/code>, and <code>i<\/code> that are general enough to be used for more than one purpose are not as informative as they could be and are usually bad names.<\/p>\n<p>Variable names should be <strong>10 to 16 characters<\/strong> long.<\/p>\n<h3>Computed-Value Qualifiers in Variable Names<\/h3>\n<p>Many programs have variables that contain computed values: <code>totals<\/code>, <code>averages<\/code>, <code>maximums<\/code>, and so on. If you modify a name with a qualifier, put the modifier at the end of the name. Try to avoid using <code>num<\/code>, instead use <code>customerCount<\/code> for total numbers of customers and <code>customerIndex<\/code> refers to a specific customer.<\/p>\n<p>By establishing this convention, you avoid the confusion you might create if you were to use both <code>totalRevenue<\/code> and <code>revenueTotal<\/code> in the same program.<\/p>\n<h3>Naming Status Variables<\/h3>\n<p><strong>Think of a better name than <code>flag<\/code> for status variables<\/strong>.<\/p>\n<p>Here are some examples of flags with bad names:<\/p>\n<pre><code>if ( flag ) ...\nif ( printFlag == 16) ...\nif ( statusFlag &amp; 0x0F) ...\n<\/code><\/pre>\n<p>Statements like <code>statusFlag = 0x80<\/code> give you no clue about what the code does unless you wrote the code or have a documentation. Here are equivalent code examples that are clearer:<\/p>\n<pre><code>if ( dataReady ) ...\nif ( reportType == ReportType_Annual ) ...\nif ( characterType &amp; PRINTABLE_CHAR ) ...\n<\/code><\/pre>\n<p>Clearly, <code>characterType = CONTROL_CHARACTER<\/code> is more meaningful than <code>statusFlag = 0x80<\/code>.<\/p>\n<h3>Naming Temporary Variables<\/h3>\n<p>They&#8217;re usually called <code>temp<\/code>, <code>x<\/code>, or some other vague and non-descriptive name. In general, temporary variables are a sign that the programmer does not yet fully understand the problem. Moreover, because the variables are officially given a &#8220;temporary&#8221; status, programmers tend to treat them more casually than other variables, increasing the chance of errors.<\/p>\n<h3>Naming Boolean Variables<\/h3>\n<ul>\n<li><strong>Keep typical boolean names in mind:<\/strong>\n<ul>\n<li><strong>done<\/strong><\/li>\n<li><strong>error<\/strong><\/li>\n<li><strong>found<\/strong><\/li>\n<li><strong>success or ok<\/strong> &#8211; if you can, replace success with a more specific name that describes precisely what it means to be successful<\/li>\n<\/ul>\n<\/li>\n<li><strong>Give boolean variables names that imply true or false<\/strong>\n<ul>\n<li>Names like <code>status<\/code> and <code>sourceFile<\/code> are poor boolean names because they&#8217;re not obviously true or false. What does it mean if <code>status<\/code> is true? For a better result, replace <code>status<\/code> with a name like  <code>statusOK<\/code>, and <code>_sourceFile_<\/code> with <code>_sourceFileAvailable_<\/code> or <code>_sourceFileFound_<\/code><\/li>\n<\/ul>\n<\/li>\n<li><strong>Use positive boolean variable names<\/strong> &#8211; negative names like <code>notFound<\/code> or <code>notDone<\/code> are difficult to read when they are negated<\/li>\n<\/ul>\n<h3>Naming Constants<\/h3>\n<p>When naming constants, name the abstract entity the constant represents rather than the number the constant refers to. <code>FIVE<\/code> is a bad name for a constant (regardless of whether the value it represents is 5.0). <code>CYCLES_NEEDED<\/code> is a good name.<\/p>\n<blockquote><p>\n  The key is that any convention at all is often better than no convention.\n<\/p><\/blockquote>\n<h2>Guidelines for a Language-Independent Convention<\/h2>\n<ul>\n<li><code>variableName<\/code> <\/li>\n<li><code>RoutineName()<\/code><\/li>\n<li><code>functionInsideClass()<\/code><\/li>\n<li><code>ClassName<\/code><\/li>\n<li><code>g_GlobalVariable<\/code><\/li>\n<li><code>CONSTANT<\/code><\/li>\n<li><code>i<\/code> or <code>j<\/code> are integer indexes.<\/li>\n<\/ul>\n<h3>Sematic Prefixes<\/h3>\n<ul>\n<li><code>c<\/code> &#8211; Count<\/li>\n<li><code>first<\/code> &#8211; The first element that needs to be dealt with in an array.<\/li>\n<li><code>g<\/code> &#8211; Global variable.<\/li>\n<li><code>i<\/code> &#8211; Index into an array.<\/li>\n<li><code>last<\/code> &#8211; The last element that needs to be dealt with in an array.<\/li>\n<li><code>lim<\/code> &#8211; The upper limit of elements that need to be dealt with in an array. Generally, <code>lim<\/code> equals <code>last + 1<\/code>.<\/li>\n<li><code>m<\/code> &#8211; Class-level variable<\/li>\n<li><code>max<\/code> &#8211; The absolute last element in an array or another kind of list. <code>max<\/code> refers to the array itself rather than to operations on the array<\/li>\n<li><code>min<\/code> &#8211; The absolute first element in an array or another kind of list.<\/li>\n<li><code>p<\/code> &#8211; Pointer.<\/li>\n<\/ul>\n<p><strong>Advantage of standardized prefixes<\/strong> &#8211; they give you all the general advantages of having a naming convention as well as several other advantages. Because so many names are standard, you have fewer names to remember in any single program or class.<\/p>\n<h2>Kinds of Names to Avoid<\/h2>\n<ul>\n<li>Avoid names with similar meanings. For example, <code>input<\/code> and <code>inputValue<\/code><\/li>\n<li>Avoid numerals in names. E.g. <code>file1<\/code> and <code>file2<\/code>. You can almost always think of a better way to differentiate between two variables than by adding a 1 or 2 onto the end of the name.<\/li>\n<li>Avoid words that are commonly misspelled in English: <code>absense<\/code>, <code>acummulate<\/code>, <code>acsend<\/code>, <code>calender<\/code>, <code>concieve<\/code>, <code>defferred<\/code>, <code>definate<\/code>, <code>independance<\/code>, <code>occassionally<\/code>, <code>prefered<\/code>, <code>reciept<\/code> and so on&#8230; <\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>I just love Steve McConnell&#8217;s classic book Code Complete 2, and I recommend it to everyone in the Software &#8216;world&#8217; who&#8217;s willing to progress and sharpen his skills.&hellip;<\/p>\n","protected":false},"author":1,"featured_media":3572,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[34],"tags":[],"class_list":["post-3654","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/posts\/3654","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/comments?post=3654"}],"version-history":[{"count":1,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/posts\/3654\/revisions"}],"predecessor-version":[{"id":3655,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/posts\/3654\/revisions\/3655"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/media\/3572"}],"wp:attachment":[{"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/media?parent=3654"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/categories?post=3654"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/nikola-breznjak.com\/blog\/wp-json\/wp\/v2\/tags?post=3654"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}