Clean Code Is Overrated Without Clean Names. Here Is What Works:

I Thought Clean Code Was Enough Until I Revisited My Own Work.

---

Usually I talk here about the optimization, cleaning, and custom visuals, but one important thing is overlooked.

Today I want to tell you about naming conventions across data analytic tools, dashboards, and documentation. When you work on long-term projects and return back after some time, you might see that the names of columns, measures, and other data fields are strange and inconsistent. It takes a toll on how much time you need to remember what it was and what the details were.

Now imagine the person who has never seen that and their reaction.

---

Universal Principles:

Before diving into specific tools, it is important to establish universal principles.

These rules apply everywhere:

• Consistency: Pick a convention and stick to it across the project. Random naming is worse than a less-than-perfect standard.

• Brevity: Names should be short but descriptive.

• Clarity: Names should describe what the object contains or represents. Avoid vague labels like data1 or final_final. As a general rule, prioritize clarity over brevity, and do not be afraid to type a few extra characters if it makes the code logic easier to follow later.

• Reserved Words: Never use system keywords (like SELECT in SQL or for in Python) as names. They cause conflicts and confusion.

• Separators and Case: Decide on a separator (underscore, dash, or none) and casing style (snake_case, camelCase, PascalCase). Apply it consistently.

These principles form the foundation for tool-specific conventions.

To ensure files and data structures work across different systems, avoid special characters (like !, @, #, $) as they can be mistaken for commands. Avoid spaces in technical filenames and backend IDs as they can cause issues on shared drives and web environments. Use underscores (_) or hyphens (-) to separate elements.

When you are including dates in names, always use the ISO standard YYYY-MM-DD.

---

SQL:

Naming choices here have long-term consequences for maintenance and queries.

Case Style: Snake Case.

In SQL, the standard recommendation is snake_case, when you use all lowercase letters with words separated by underscores.

For example, use customer_orders rather than CustomerOrders.This is crucial because many databases are case-insensitive or handle casing inconsistently. With standard lowercase, your code remains valid regardless of running on a case-sensitive or case-insensitive system.

It also provides a visual contrast from SQL keywords (like SELECT and FROM), which are written in uppercase.

Tables: Singular vs. Plural.

There is a debate regarding table names.

Some argue that a table represents a collection, so it should be plural (customers). Others argue that a table defines an entity, so it should be singular (customer).While both are valid, the most important rule is to pick one and use it throughout the entire database and all the projects.

However, many developers prefer singular names because they prevent linguistic complexities (e.g., person vs. people) and make query writing more intuitive.

Explicit Keys:

Add suffixes for clarity:

• _id for identifiers,

• _dt or _date for dates,

• _amt for amounts,

• _flg or _flag for booleans.

Name constraints explicitly:

• pk_customers for primary keys,

• fk_orders_customer_id for foreign keys,

• idx_orders_date for indexes,

• chk_orders_amount_positive for check constraints.

Avoid Reserved Words:

Never use SQL reserved keywords (like SELECT, DATE, USER, or GROUP) as table or column names.

Using these words can cause syntax errors or require extra wrapping (e.g., [User] or "User") to function.

If a reserved word is still tempting, choose a more descriptive alternative, such as start_date or user_account.

Check the official documentation for your specific dialect, as each one has some differences.

Formatting:

• SQL Keywords: Write commands in uppercase (SELECT, FROM, WHERE) to distinguish them from user-defined names.

• Length: Keep names under 30 characters to avoid system limits.

Tools like SQLFluff enforce conventions automatically.

---

Python:

When we want to run deeper analysis, we often use Python. Its naming conventions are governed by PEP 8, the official style guide.

Following these rules ensures your code looks professional and other people understand it.

Keywords:

Python has a fixed list of reserved words (if, else, class, def). These words cannot be used as variable names. You can check them with this code:

import keyword
print(keyword.kwlist)

Variables and Functions:

For variables and functions, use snake_case.

This means all lowercase letters with underscores separating words (e.g., calculate_total, user_list). This style is a hard requirement for PEP 8 compliance and provides better visual separation for long, descriptive names.

Units in Names: Add units when relevant (delay_seconds, price_usd). This prevents ambiguity.

Avoid Abbreviations: Modern editors support auto-completion. Saving keystrokes is not worth sacrificing clarity.

Constants:

Values that are intended to remain static throughout the execution of a script should be written in SCREAMING_SNAKE_CASE (all uppercase with underscores).

For example, MAX_RETRIES or DEFAULT_TIMEOUT. This signals to other developers that these values should not be modified.

Classes:

Class names follow a different convention: PascalCase (also known as CapWords), where each word starts with a capital letter and there are no underscores (e.g., DataFrameBuilder, CustomerProfile). This visual distinction helps developers instantly recognize classes versus functions or variables.

Interfaces and Base Classes: Avoid unnecessary prefixes like I or Base. Name the general class clearly (Truck) and specify subclasses (FireTruck, TrailerTruck).

Explicit vs. Implicit:

Modern Python practices, especially in data science, favor the explicit names.

While single-letter variables (like x or i) are acceptable in math-heavy contexts or loops, you should avoid them elsewhere.

Use tools like black or flake8. The rules there will enhance readability in data scripts and pipelines.

---

Power BI:

Once basic preparations are done, we are ready to import the data to Power Query.

Power Query (M):

• Column Names: Split datetime fields into separate date and time columns. If there are 2 or more categories in the field (for example, gender + age), also split it.

• Case and Separators: Unlike SQL or Python, user-facing tables and columns in Power BI should use natural language with spaces. Instead of cust_id, use Customer ID. The goal is to make the model business-friendly and easy for non-technical users to navigate.

• Reserved Words: Avoid M keywords. If unavoidable, quote names (#"Column Name").

• Avoid redundant words: Don’t use Total unless necessary (Revenue instead of Total Revenue).

Data Model:

• Calendar Table: Use consistent names for date-related fields (month_name, year, week_number).

• Table Naming: Prefix dimension tables with dim_ and fact tables with fact_.

Measures:

Measure names should be concise and meaningful so users know exactly what they represent (e.g., Revenue, Profit Margin). Do not prefix data types to the name (e.g., AmountInt) as this is unnecessary for the end user.

For time-intelligence calculations, use standard suffixes to keep names organized. Common conventions include YTD (Year-to-Date), PY (Previous Year), and YoY (Year-over-Year).

• Clarity: Measures should be self-explanatory (Total Sales, Average Discount).

• Reserved Words: Avoid conflicts with DAX functions. Use brackets consistently ([Measure Name]).

Measures require precision:

• Descriptive: Revenue YTD over Total Revenue.

• Suffixes: YTD, PY, YoY, % (e.g., Profit Margin %).

• Prefixes: Group similar measures (e.g., Sales_Revenue).

Add descriptions for tooltips.

DAX Variables:

Inside your DAX formulas, variable names should be distinct from table columns to avoid confusion.

A common practice is to use PascalCase for variables (e.g., TotalSales). Some developers prefer starting variable names with an underscore (e.g., _py_sales) to distinguish them from tables and columns.

In DAX code, use PascalCase with an underscore prefix to distinguish variables from tables and columns:

VAR _TotalSales = SUM(Sales[Amount])
VAR _AverageSales = AVERAGE(Sales[Amount])
VAR _SalesGrowth = DIVIDE(_TotalSales - _PreviousYearSales, _PreviousYearSales)
RETURN _SalesGrowth

---

Dashboards: User Experience (UX):

Here I want to show you the best practices on how to use naming in dashboards in general.

At the visualization layer, naming becomes a component of User Experience (UX).

The names chosen here will guide the user through the narrative of the data.

Titles:

Dashboard titles should be descriptive and clear.

A recommended hierarchical naming convention involves the Project Key, Purpose, and Timeframe (e.g., Sales: Monthly Revenue - Q4 2024). This groups dashboards by project alphabetically and clarifies if the data is current or historical.

Avoid generic names like “My Dashboard” or “Project Dashboard,” which provide no context. If the dashboard is a work-in-progress, label it clearly (e.g., [DRAFT] Sales Overview).

Format titles consistently: [Project/Unit]: [Purpose] ([Timeframe]) (e.g., “Sales: Monthly Performance Q4 2025”).

Include context: purpose, timeframe, status (e.g., “Draft”). Avoid generics like “My Dashboard.”

Visuals and Charts:

Chart titles should be active and descriptive, answering a specific question. Instead of “Sales,” use “Monthly Net Sales Trend”. This reduces the cognitive load on the user by explaining exactly what they are looking at.

For technical component names (in development), use consistent separators:

• revenue_chart_monthly or RevenueChartMonthly.

• customer_filter_region or CustomerFilterRegion.

Navigation and Hierarchy:

Within a dashboard, panel and page names should reference both the dashboard and the specific visualization.

If you use the term “Gross Revenue” on one chart, do not switch to “Total Sales” on another without a valid reason.

• Titles and Subtitles: Keep them clear and standardized. End users should understand metrics without needing extra explanation.

• KPI Labels: Use descriptive names (Revenue Growth %, not RevGr).

• Titles/Subtitles: Standardize across pages. A dashboard should feel cohesive.

Use standard time intelligence suffixes:

• YTD: Year to Date (Revenue YTD).

• QTD: Quarter to Date (Sales QTD).

• PY: Previous Year (Revenue PY).

• YoY: Year over Year (Growth % YoY).

• MAT: Moving Annual Total (Sales MAT).

Use a hierarchical naming structure:

Format: [Project/Business Unit]: [Purpose] - [Sub-purpose/Timeframe]

Examples:

• Sales: Monthly Performance - Q4 2024.

• HR: Onboarding Metrics - Active.

• Marketing: Campaign ROI - 2024 Annual.

---

Documentation:

After we have built a dashboard with all measures and complex formulas, we need to record everything.

Versioning and Lifecycle:

Never label a document as “final” because updates inevitably lead to confusing names like “final_final”. Instead, use version numbers (e.g., v01, v02) to depict its place in the sequence. Always include leading zeros (e.g., 01 rather than 1) so that files sort correctly even when you reach double digits.

• Drafts: Use revision letters (RevA, RevB).

• Collaborations: Add initials (RevA_JD).

• Final Versions: Replace with numbers (0). Avoid “final_final.”

Structured File Names:

A predictable file name should be separated into unique elements, including a subject and a date.

Order these elements from the most significant to the least:

Example Pattern: [Date]_[Project]_[Description]_[Version]

Example File: 2025-12-20_Sales_MonthlyReport_v03.xlsx.

No naming convention is sufficient without a master document that explains its logic. Maintain a “README” file or a central wiki that documents your naming rules, abbreviations, and code definitions.

README and Data Dictionaries:

Every project should include a README file explaining:

• The naming conventions used

• Abbreviations and their meanings

• Folder structure and organization

• Contact information for questions

Create a data dictionary for complex projects, documenting all codes, abbreviations, and business rules in a central spreadsheet or markdown file.

• Underscores: Use underscores instead of spaces (Project_XYZ_2025-01-01).

• ISO Date Format: Always use YYYY-MM-DD for chronological sorting.

• Special Characters: Avoid them entirely. Stick to letters, numbers, and underscores.

Status Indicators:

• Labels: Use clear indicators like Draftor Signed.

• PDF for Distribution: Save final versions as PDFs.

Documentation is the bridge between technical work and organizational memory. Proper naming makes it reliable and easy to navigate.

---

It is better to have a slightly imperfect naming convention that is applied across the entire system than to have “perfect” names that vary from file to file. Random naming makes a system nearly impossible to decipher after you build it.

Follow these recommendations. :

• Start with new projects. Don’t try to rename an entire legacy database overnight. Apply standards to new work and gradually refactor critical areas.

• Do regular audits. Review naming conventions quarterly. Remove deprecated patterns and add new ones as tools evolve.

• Provide training and onboarding. Make naming conventions part of new hire onboarding. Include them in code review checklists.

• Start small. Pick one area: SQL tables or Python functions, and standardize it today.

---

What naming conventions have worked best in your projects?

Share your experiences in the comments below.👇

Subscribe for more practical data insights.