How to Add Comments in Power BI DAX

Writing clean DAX is one thing, but writing DAX that you and your colleagues can actually understand six months from now is another skill entirely. Using comments within your formulas is the key. This guide will walk you through the proper ways to add notes and documentation inside your Power BI measures and columns, making your reports easier to maintain, debug, and share.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Why Should You Comment Your DAX Formulas?

Dedicating a few extra seconds to comment on your DAX might feel like a chore at the time, but it’s one of the most valuable habits a Power BI developer can build. Think of it as leaving a helpful trail of breadcrumbs for your future self - and for anyone else who works on your reports.

Here’s why it’s so important:

• Improves Readability and Understanding: A complex formula might make sense to you in the moment, but coming back to it later can be confusing. Comments clarify the logic, the business rules, and the purpose behind your calculations at a glance.
• Simplifies Collaboration: When working in a team, comments are essential for communication. Another team member can instantly understand your formula's intent without having to reverse-engineer your logic. This streamlines everything from code reviews to handover processes.
• Speeds Up Debugging: If a measure isn’t working correctly, comments explaining each piece of the logic make it much easier to pinpoint where things are going wrong. You can also use comments to temporarily disable parts of a formula to test individual components.
• Acts as In-Formula Documentation: Instead of keeping notes in a separate Word doc or an easily lost text file, comments place the documentation exactly where it's needed - right inside the formula field.

Ultimately, a well-commented report is a sign of a professional and considerate data practitioner. It shows you care about creating something that is not just functional but also maintainable and scalable.

How to Add Comments in Power BI DAX

DAX offers three simple syntaxes for adding comments, each suited for different situations. Let's cover how to use each one, with examples.

1. Single-Line Comments with Double-Forward Slashes (//)

This is the most common way to add short, single-line comments. Simply type two forward slashes // and everything following it on that same line will be ignored by the DAX engine.

It’s perfect for adding quick notes, labeling variables, or explaining a specific filter condition.

Example - Before Commenting:

Here's a standard measure for year-over-year sales growth.

Sales YoY % = 
VAR CurrentYearSales = CALCULATE([Total Sales], 'Date'[Year] = 2024)
VAR PreviousYearSales = CALCULATE([Total Sales], 'Date'[Year] = 2023)
RETURN
    DIVIDE(
        CurrentYearSales - PreviousYearSales,
        PreviousYearSales
    )

Example - After Commenting:

The commented version is much easier to understand at a glance.

Sales YoY % = 
// This measure calculates the percentage change in sales from 2023 to 2024.

VAR CurrentYearSales = CALCULATE([Total Sales], 'Date'[Year] = 2024) // Defines the total sales for the current year.
VAR PreviousYearSales = CALCULATE([Total Sales], 'Date'[Year] = 2023) // Defines the total sales for the previous year.

RETURN
    // Use DIVIDE to handle potential zero or blank values in last year's sales.
    DIVIDE(
        CurrentYearSales - PreviousYearSales,
        PreviousYearSales
    )

Pressing Ctrl + / (Cmd + / on Mac) is a handy keyboard shortcut to quickly comment or uncomment the line where your cursor is.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

2. Single-Line Comments with Double Hyphens (--)

Alternatively, you can use two hyphens -- to create a single-line comment. This style is familiar to anyone who has worked with standard SQL, and DAX accepts it for the same purpose as the double slash.

Functionally, there is no difference between // and --. The choice between them often comes down to personal preference or team convention. Many DAX developers prefer // as it feels more native to the Power BI environment, but -- is perfectly valid.

Example:

Sales In California = 
-- This measure specifically filters total sales for the state of California
CALCULATE (
    [Total Sales],
    'Customers'[State] = "California" -- Hardcoded filter for CA
)

3. Multi-Line or Block Comments (/.../)

When you need more space for a detailed explanation, use block comments. A block comment starts with a slash and an asterisk /* and ends with an asterisk and a slash */. Everything between these two markers will be treated as a comment, even if it spans multiple lines.

This type of comment is ideal for:

• Writing a detailed header for a complex measure, including its purpose, author, and revision date.
• Explaining multiple variables or a tricky part of the formula logic.
• Temporarily "commenting out" large sections of your DAX for debugging purposes.

Example:

Here, a block comment at the top provides all the necessary context for a more complex measure.

High-Value Customer Sales % = 
/*
  Measure Purpose: Calculates the percentage of total sales that come from "High-Value" customers.
  Author: Jane Smith
  Date Created: 2024-05-20
  Business Logic: A "High-Value" customer is defined as anyone who has made purchases totaling over $2,000 in the last 12 months. This logic is managed in a calculated column in the 'Customers' table.
*/
VAR HighValueSales = 
    CALCULATE(
        [Total Sales], 
        'Customers'[Customer Segment] = "High-Value"
    )

VAR AllSales = 
    CALCULATE(
        [Total Sales], 
        REMOVEFILTERS('Customers'[Customer Segment])
    )
RETURN
    DIVIDE(HighValueSales, AllSales)

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Best Practices for Writing Useful DAX Comments

Knowing how to comment isn't enough, knowing what and why to comment is what makes the practice truly valuable. Here are some guidelines to follow.

Comment the "Why," Not Just the "What"

A good comment clarifies intent. The DAX code itself shows what it's doing (e.g., summing a column). Your comment should explain why you are doing it in that particular way.

A less helpful comment (the "what"):

// Calculates the sum of the Sales amount

This is redundant because the formula (SUM(Sales[Amount])) already says that.

A more helpful comment (the "why"):

// Calculates net sales, defined as gross sales minus returns. Pre-2023 data may be inconsistent.

This comment provides valuable context about the business logic that you couldn't get from the DAX code alone.

Use Comments for Version Control within Measures

When you update a complex measure, you can leave a log of the changes. This is extremely helpful in a team environment or for tracking your own changes over time.

/* 
    _v2 - Updated May 21, 2024 by Jane D. 
    - Changed the time intelligence filter from DATESYTD to a rolling 12-month period based on new LTM reporting requirements. Original logic commented out below for reference.
*/

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Use Comments for Debugging Your Formulas

This is one of the most powerful uses for comments. If a complex formula returns an error or an unexpected result, you can systematically disable parts of it to isolate the problem.

Imagine this formula is causing an error:

Filtered Sales = 
CALCULATE(
    [Total Sales],
    FILTER(
        'Products',
        'Products'[Category] = "Bikes"
    ),
    KEEPFILTERS('Customers'[Country] = "USA")
)

Instead of deleting lines, you can use block comments to test components. For example, let's see if the product category filter is the issue by commenting it out:

Filtered Sales = 
CALCULATE(
    [Total Sales],
    /*
    FILTER(
        'Products',
        'Products'[Category] = "Bikes"
    ),
    */
    KEEPFILTERS('Customers'[Country] = "USA")
)

Now you can run the formula and see if it works with only the KEEPFILTERS function applied. This helps you narrow down precisely where the problem resides without having to delete and retype your code.

Be Consistent with Your Commenting Style

Decide on a convention and stick with it. Whether you use // or --, place comments above the line or at the end of it, consistency makes your code predictable and easier to read for everyone. If you're on a team, establish these guidelines together. This simple step can drastically improve the group's productivity.

Final Thoughts

Adding comments to your DAX code with //, --, or /*...*/ is a quick habit that pays huge dividends. It transforms confusing formulas into clear, shareable, and maintainable assets, saving you and your team countless hours troubleshooting down the road. Make it a regular part of your Power BI development process.

Of course, sometimes the challenge isn't just writing one DAX formula, but connecting all your different data sources together to get a clear picture in the first place. That's why we created Graphed - to remove that complexity entirely. Instead of struggling with the steep learning curve of tools like Power BI and languages like DAX, we enable you to instantly connect your platforms and build real-time dashboards just by asking questions in plain English.