{"id":618,"date":"2026-01-07T21:49:35","date_gmt":"2026-01-07T21:49:35","guid":{"rendered":"https:\/\/haptonstahl.org\/polimath\/?p=618"},"modified":"2026-01-14T00:23:41","modified_gmt":"2026-01-14T00:23:41","slug":"good-practices-naming-things","status":"publish","type":"post","link":"https:\/\/haptonstahl.org\/polimath\/good-practices-naming-things\/","title":{"rendered":"Good practices: Naming Things"},"content":{"rendered":"\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\">\nThere are only <a href=\"https:\/\/martinfowler.com\/bliki\/TwoHardThings.html\">two hard things<\/a> in Computer Science: cache invalidation and naming things.<br>\n<\/blockquote>\n\n\n\n<p class=\"\">Bad names create confusion. Good names:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Provide <strong>clarity to consumers<\/strong> about what to find inside by telling us <em>why<\/em> we have the named thing.<\/li>\n\n\n\n<li class=\"\">Provide <strong>guidance to producers<\/strong> about what should and should not go inside, and tell us <em>how<\/em> we create the named thing.<\/li>\n\n\n\n<li class=\"\">Are <strong>easy to use<\/strong>: concise, memorable, easy-to-spell, not random or disconnected from how and why we have the named thing.<\/li>\n\n\n\n<li class=\"\"><strong>Avoid &#8220;collisions&#8221;<\/strong> = repeating a name of something else that is not distinguishable from context.<\/li>\n<\/ul>\n\n\n\n<p class=\"\">This is not a complete guide to naming, but rather a compilation of good practices<sup data-fn=\"51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa\" class=\"fn\"><a id=\"51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa-link\" href=\"#51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa\">1<\/a><\/sup> that generalize what I have found useful. We&#8217;ll discuss:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Coding<\/li>\n\n\n\n<li class=\"\">Projects<\/li>\n\n\n\n<li class=\"\">Stories: presentations, reports, individual slides and sections<\/li>\n\n\n\n<li class=\"\">Email subjects<\/li>\n\n\n\n<li class=\"\">Calendar events<\/li>\n\n\n\n<li class=\"\">Children<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Coding<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">variables, methods, file names\n<ul class=\"wp-block-list\">\n<li class=\"\">snake_case: compatible across languages and file systems<\/li>\n\n\n\n<li class=\"\">lower case: easy to remember<\/li>\n\n\n\n<li class=\"\">no hyphens: hyphens mean subtraction in mathematical languages like <code>R<\/code><\/li>\n\n\n\n<li class=\"\">no spaces: spaces in file names complicate file handling<\/li>\n\n\n\n<li class=\"\">methods are verbs<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li class=\"\">CONSTANT: CAPITALIZED, singular or plural<\/li>\n\n\n\n<li class=\"\">ClassDefinition: TitleCase, singular<\/li>\n\n\n\n<li class=\"\">git-repository: lower-case-and-hyphenated<\/li>\n\n\n\n<li class=\"\">Make names descriptive but somewhat concise.<\/li>\n\n\n\n<li class=\"\">The length of a variable name should be proportional to the scope of the variable to avoid collisions and hint at where it is defined. Examples of good names:\n<ul class=\"wp-block-list\">\n<li class=\"\"><code>i<\/code> for the index of a very short code block<\/li>\n\n\n\n<li class=\"\"><code>customer_id<\/code> within a class or function<\/li>\n\n\n\n<li class=\"\"><code>bridge_customer_id<\/code> when assigned by the &#8220;Bridge&#8221; team<\/li>\n\n\n\n<li class=\"\"><code>CUSTOMER_ID_ENCRYPTION_SALT_PREFIX<\/code> for use across a wide scope<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Projects<\/h2>\n\n\n\n<p class=\"\">There are generally two consumers of project names:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\"><strong>Workers<\/strong>: those working on the project<\/li>\n\n\n\n<li class=\"\"><strong>Stakeholders<\/strong>: leadership and everyone else<\/li>\n<\/ul>\n\n\n\n<p class=\"\">This suggests two-part names: &#8220;{Method} {Purpose}&#8221; or &#8220;{Purpose} {Method}&#8221;<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li class=\"\"><strong>Purpose or Value<\/strong>: Tells stakeholders how to use or <strong>why<\/strong> they should care. Avoids collisions among workers&#8217; projects.<\/li>\n\n\n\n<li class=\"\"><strong>Method<\/strong> or Tool: Stakeholders avoid collisions (&#8220;This is the {purpose} that&#8217;s different because it uses {method}&#8221;). Insufficient for workers, who use the same method on other projects, so we add the purpose.<\/li>\n<\/ol>\n\n\n\n<p class=\"\">Examples: AI Pricing Model<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Stories<\/h2>\n\n\n\n<p class=\"\">Don&#8217;t <a href=\"https:\/\/share.google\/0iJPjDgaqcLMCtJSx\">bury the lede<\/a>: tell the story in the title (name). Start with the <em>conclusion<\/em>. Don&#8217;t wait until the end<sup data-fn=\"6579a6dd-0021-48c0-bb83-0e387ec9909f\" class=\"fn\"><a id=\"6579a6dd-0021-48c0-bb83-0e387ec9909f-link\" href=\"#6579a6dd-0021-48c0-bb83-0e387ec9909f\">2<\/a><\/sup> to reveal the answer to the question.  <del>If<\/del> <em>When<\/em> you lose the audience&#8217;s attention, it&#8217;s too late. How often do you finish your presentation early after covering all of your planned points? (Not often.) How often does every consumer read to the end? (Not often.)<\/p>\n\n\n\n<p class=\"\">Too often, we tell the history of how we reached a conclusion. Your audience doesn&#8217;t care how you spent your week. The answer is the most important part. After giving the answer, make a concise, reasoned argument as to why they should believe the answer; this will have selected parts of the history but not every blind alley. This isn&#8217;t an itemized time sheet.<\/p>\n\n\n\n<p class=\"\">Examples:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Bad presentation\/report title: &#8220;Q4 Performance&#8221;<\/li>\n\n\n\n<li class=\"\">Good presentation\/report title: &#8220;2025 Q4 Performance: Continued Growth&#8221;<\/li>\n<\/ul>\n\n\n\n<p class=\"\">Putting the full time period (including year) at the beginning means that default file sorting (alphabetical) puts files in chronological order.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Bad slide\/section title: &#8220;Proposed Organizational Structure&#8221;<\/li>\n\n\n\n<li class=\"\">Good slide\/section title: &#8220;Centralized Services Reduce Unnecessary Redundancy&#8221;<\/li>\n<\/ul>\n\n\n\n<p class=\"\">The good title has a verb that connects the <em>how<\/em> to the <em>why<\/em>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Email subjects<\/h2>\n\n\n\n<p class=\"\">Subject lines (usually) should tell the story. Two notes:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">If the contents are sensitive, avoiding the answer (or even the specific question) may make it easier for recipients to avoid leaking when sharing their screen or when someone stops by their desk.<\/li>\n\n\n\n<li class=\"\">Remember that emails often are forwarded, so subjects should be descriptive and avoid collisions for people one step removed from the recipients, if possible.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Calendar events<\/h2>\n\n\n\n<p class=\"\">Conciseness is necessary because only the first part of the event title is visible in a one-week view without opening the event.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Don&#8217;t write &#8220;meeting&#8221;. We know it&#8217;s a meeting.<\/li>\n\n\n\n<li class=\"\">Don&#8217;t write &#8220;Discussion&#8221; or &#8220;Presentation&#8221;. We know.<\/li>\n\n\n\n<li class=\"\">Focus on the goal of the meeting.\n<ul class=\"wp-block-list\">\n<li class=\"\">Bad: &#8220;{sender} &#8211; {recipient}&#8221;. Looks like bad news.<\/li>\n\n\n\n<li class=\"\">Good: &#8220;1-1: {sender} \/ {recipient}&#8221;. Looks routine.<\/li>\n\n\n\n<li class=\"\">Better: &#8220;1-1: {recipient} \/ {sender}&#8221;. (Recipient first.) When the title gets cut off, you can still see who you&#8217;re meeting with.<\/li>\n\n\n\n<li class=\"\">Bad: &#8220;Org update&#8221;. Looks like terrible news.<\/li>\n\n\n\n<li class=\"\">Good: &#8220;Org update&#8221; (the same?) <strong>but<\/strong> let them know <em>before<\/em> sending the invitation that it&#8217;s not bad news for them.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<p class=\"\">In general, avoid sending invitations that could be interpreted as bad news (such as the recipient being fired, you quitting, etc.)<\/p>\n\n\n\n<p class=\"\">Bonus: Give context inside the invitation&#8217;s description: agenda, suggested\/expected preparation, goals, in-scope\/out-of-scope. The invitation, including description, is the &#8220;name&#8221; of the meeting.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Out-of-Office &#8220;events&#8221;<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Bad: &#8220;Out of Office&#8221;. Wait, <em>who<\/em> is out of the office? The recipient? That&#8217;s what it will look like to them.<\/li>\n\n\n\n<li class=\"\">Good: &#8220;{sender} OOO Jan 12-20&#8221;. Tells the whole story concisely.<\/li>\n<\/ul>\n\n\n\n<p class=\"\">Bonus good practices:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">Make them &#8220;all-day&#8221; events, not an event repeated every day. This makes it appear as a single bar across the top of the calendar.<\/li>\n\n\n\n<li class=\"\">Don&#8217;t use the event you send to others as a way to block off your time; if it blocks off the day, then <em>their<\/em> calendar will be blocked off! To block off the hours, create a separate event that you don&#8217;t send out, 12 am to 12 am the next day, that <em>is<\/em> repeated. That way, others will know you&#8217;re not available.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Children<\/h2>\n\n\n\n<p class=\"\">Call them whatever you like! However, here are some considerations.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"\">The child will have the name for their entire life. Try to avoid <a href=\"https:\/\/youtu.be\/-Z1Ple-qYuU\">making therapy inevitable<\/a>.<\/li>\n\n\n\n<li class=\"\">You might aim for something that:\n<ul class=\"wp-block-list\">\n<li class=\"\">Someone reading it will know how to pronounce it.<\/li>\n\n\n\n<li class=\"\">Someone hearing it will have a good chance of knowing how to spell it.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li class=\"\">If you get &#8220;creative&#8221; with the spelling, they will have to spell their name and help others pronounce it. Forever.<\/li>\n\n\n\n<li class=\"\">They will grow up. You can call them &#8220;Stevie&#8221; when they are young, but you might want to put &#8220;Stephen&#8221; on their birth certificate.<\/li>\n\n\n\n<li class=\"\">Names from today&#8217;s culture will reveal their age. This can lead to ageism 50 years from now. When you hear about a &#8220;Karen&#8221; or a &#8220;Gary&#8221;, do you think Gen Z? Probably not.<\/li>\n\n\n\n<li class=\"\">Family names can be deeply meaningful &#8212; great! Some should be avoided Example: my dear grandfather, <a href=\"https:\/\/haptonstahl.org\/polimath\/thank-you-is-always-appropriate\/\">Adolphus<\/a>.<\/li>\n<\/ul>\n\n\n\n<p class=\"\">These practices aren&#8217;t intended to be dogma, but now if you choose to go a different way, you&#8217;ll have some idea about the tradeoffs.<\/p>\n\n\n\n<figure class=\"wp-embed-aspect-16-9 wp-has-aspect-ratio wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube\"><div class=\"wp-block-embed__wrapper\">\n<iframe loading=\"lazy\" title=\"The More You Know\" width=\"500\" height=\"281\" src=\"https:\/\/www.youtube.com\/embed\/Zmvt7yFTtt8?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen><\/iframe>\n<\/div><\/figure>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n<ol class=\"wp-block-footnotes\"><li id=\"51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa\">&#8220;Best&#8221; practices are debatable. &#8220;Good&#8221; practices avoid known pitfalls and needless debates. <a href=\"#51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa-link\" aria-label=\"Jump to footnote reference 1\">\u21a9\ufe0e<\/a><\/li><li id=\"6579a6dd-0021-48c0-bb83-0e387ec9909f\">I&#8217;m looking at you, academic researchers. <a href=\"#6579a6dd-0021-48c0-bb83-0e387ec9909f-link\" aria-label=\"Jump to footnote reference 2\">\u21a9\ufe0e<\/a><\/li><\/ol>","protected":false},"excerpt":{"rendered":"<p>Bad names create confusion. Good names: This is not a complete guide to naming, but rather a compilation of good practices1 that generalize what I have found useful. We&#8217;ll discuss: Coding Projects There are generally two consumers of project names: This suggests two-part names: &#8220;{Method} {Purpose}&#8221; or &#8220;{Purpose} {Method}&#8221; Examples: AI Pricing Model Stories Don&#8217;t [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":622,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"nf_dc_page":"","pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":"[{\"content\":\"\\\"Best\\\" practices are debatable. \\\"Good\\\" practices avoid known pitfalls and needless debates.\",\"id\":\"51ecfdf7-8a0a-4e73-8ca3-173cd9bdd5aa\"},{\"content\":\"I'm looking at you, academic researchers.\",\"id\":\"6579a6dd-0021-48c0-bb83-0e387ec9909f\"}]"},"categories":[6,5],"tags":[19],"class_list":["post-618","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-data-science","category-leadership","tag-good-practices"],"_links":{"self":[{"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/posts\/618","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/comments?post=618"}],"version-history":[{"count":4,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/posts\/618\/revisions"}],"predecessor-version":[{"id":637,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/posts\/618\/revisions\/637"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/media\/622"}],"wp:attachment":[{"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/media?parent=618"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/categories?post=618"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/haptonstahl.org\/polimath\/wp-json\/wp\/v2\/tags?post=618"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}