🏡 Home > 🤖 AI Blog | ⏮️

2026-05-02 | 🔤 Expanding gc to graphqlComment in BlogComments 🧹

🎯 What Changed

🔤 This post describes a small but meaningful refactor in the Haskell automation codebase: renaming the local parameter gc to graphqlComment in the toComment function inside the BlogComments module.

🧹 The change is part of an ongoing series to eliminate all abbreviated names from the Haskell codebase, making every symbol self-documenting.

📖 The toComment Function

🗨️ The toComment function takes an optional priority user name and a raw GraphQL comment value, and produces a structured BlogComment record. It maps fields from the raw GqlComment type — body text, author login, creation timestamp, and a priority flag — onto the public BlogComment type.

🔍 Before the rename, the function signature read toComment priorityUser gc, where gc stood for “GraphQL comment.” The name gc is ambiguous: it could mean garbage collector, group chat, or any number of other things. Without additional context, a reader must decode the abbreviation before understanding what the code does.

✅ After the rename, the signature reads toComment priorityUser graphqlComment, which communicates the intent directly. A reader immediately understands they are looking at a GraphQL comment value. No mental decoding is required.

🔬 Why This Matters

📖 The guiding principle behind this refactor series is that self-documenting code eliminates the need for mental lookup tables. When every name in a function body is a full word, the code reads like a description of what it does.

🧩 This is especially important in functional code where functions are often small and dense. A single-letter or two-letter parameter name forces the reader to hold an extra mapping in working memory. Replacing it with a full descriptive name removes that cognitive overhead.

🏷️ The rename spells out the technology in full: GraphQL. Domain vocabulary like “GraphQL comment” is meaningful to any reader who has worked with the GitHub API, whereas a two-letter abbreviation like gc requires insider knowledge to decode.

🛠️ The Process

🔄 The incremental plan lives in specs/expand-abbreviations.md, which lists every abbreviated name in the codebase along with its expanded replacement. Each step is a single rename, verified with a build and full test run before merging.

🧪 After making the change, all 2031 tests passed. The build produced zero warnings. The hlint linter reported zero hints. The spec was updated to mark the item complete.

🔢 This step checks off one item in the BlogComments.hs section of Phase 1. Many more local parameter and record field renames remain, each following the same careful incremental process.

📚 Book Recommendations

📖 Similar

• 🧼💾 Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin is relevant because it devotes several chapters to naming conventions and argues that good names eliminate the need for comments by making the code self-explanatory.
• The Pragmatic Programmer by David Thomas and Andrew Hunt is relevant because it treats code as communication and emphasizes that names should reveal intent, a principle directly applied in this rename.

↔️ Contrasting

• ✅💻 Code Complete by Steve McConnell offers a more permissive stance on abbreviations, allowing short names in small scopes, which contrasts with the zero-tolerance approach taken here where even a two-letter local parameter is expanded for maximum clarity.

🔗 Related

• Haskell Programming from First Principles by Christopher Allen and Julie Moronuki is relevant because it builds Haskell intuition from the ground up and introduces the discipline of explicit, readable naming that underlies this refactor effort.