How to Add Comments to Power BI DAX Code

You build a DAX measure that works perfectly. Six months later, you — or someone on your team — opens it and has no idea what it does or why it was written that way.

That is the silent cost of uncommented code.

Power BI is used by more than 250,000 organizations worldwide and has over 5 million monthly active users, according to Microsoft. With that scale comes an enormous amount of DAX code — measures, calculated columns, and queries — that teams write, inherit, and maintain every day.

Commenting your DAX code is one of the simplest habits that separates professionals who build reports others can actually maintain from those who leave a trail of confusion.

This guide covers everything you need: the two commenting methods in DAX, where to use them, real code examples, and best practices that keep your work clean and readable.

Why Commenting Your DAX Code Actually Matters

📊 Stat: Developers spend up to 40% of their time reading and understanding existing code rather than writing new code. — Stack Overflow Developer Survey

DAX is not the most self-documenting language. A measure that calculates rolling 12-month revenue adjusted for returns, filtered by active customers, doesn’t explain itself. Without comments, the next person to open it — possibly you — has to reverse-engineer the logic from scratch.

Here is what uncommented DAX code actually costs you:

• Time lost debugging logic you didn’t write (or wrote and forgot)
• Errors introduced when someone misunderstands what a measure does
• Slower onboarding for new team members joining live projects
• Reports that become “black boxes” no one wants to touch

Research from the Software Engineering Institute shows that teams with well-documented code report up to 50% fewer bugs during maintenance phases. The same principle applies to your Power BI models.

Commenting is not extra work. It is the work that saves future work.

The Two Ways to Add Comments in DAX

DAX supports two commenting styles, both borrowed from standard SQL syntax. Understanding when to use each one makes your code significantly easier to read.

Single-Line Comments with —

The double dash (—) tells DAX to ignore everything that follows on that line. This is your everyday comment — fast to type, perfect for explaining a single step or flagging a note.

— Calculate total revenue for the selected period

Total Revenue =

    SUMX(

        Sales,

        Sales[Quantity] * Sales[Unit Price]  — multiply qty by price per row

    )

Single-line comments work anywhere inside your DAX expression. You can put them at the start of a line to describe what follows, or at the end of a line to annotate a specific value or function call.

There is also a second single-line syntax that works identically:

// This syntax also creates a single-line comment

Active Customers =

    CALCULATE(

        DISTINCTCOUNT(Customers[CustomerID]),

        Customers[Status] = “Active”  // only count active records

    )

Both — and // are valid in Power BI Desktop and DAX Studio. Most practitioners default to — because it mirrors SQL conventions, but either works.

Multi-Line Comments with /* */

When you need to explain something in more depth — a complex formula, an important assumption, or a section of logic that isn’t obvious — use the block comment syntax.

/*

  Rolling 12-Month Revenue

  Uses DATESINPERIOD to look back 12 months from the last date in context.

  Filtered to exclude returns (negative quantities).

  Author: Analytics Team | Last updated: Q1 2024

*/

Rolling 12M Revenue =

    CALCULATE(

        [Total Revenue],

        DATESINPERIOD(

            ‘Date'[Date],

            LASTDATE(‘Date'[Date]),

            -12,

            MONTH

        ),

        Sales[Quantity] > 0  — exclude returns

    )

Block comments are especially useful for:

• Documenting the business logic behind a complex measure
• Explaining why a specific filter or function was chosen
• Adding version or author notes at the top of a measure
• Temporarily disabling a section of code during testing

Where You Can Add DAX Comments in Power BI

Comments are supported in every location where you write DAX in Power BI Desktop. Here is where you will use them most.

Measure Editor

The most common place to add comments is directly inside a measure. Click any measure in your Fields pane, open it in the formula bar, and type your comment above or inside the expression.

Pro tip: Expand the formula bar (drag it taller) to see your full measure with comments. Cramped editing is one reason people skip commenting — give yourself space.

/*

  Profit Margin %

  Calculated as: (Revenue – COGS) / Revenue

  COGS pulled from the CostOfGoods table via relationship.

*/

Profit Margin % =

    DIVIDE(

        [Total Revenue] – [Total COGS],

        [Total Revenue],

        0  — return 0 if revenue is blank/zero to avoid division error

    )

Calculated Columns

Calculated columns benefit from comments that explain what category, bucket, or value is being assigned and why the logic was written as it was.

— Segment customers into tiers based on lifetime value

Customer Tier =

    SWITCH(

        TRUE(),

        Customers[LTV] >= 10000, “Platinum”,  — top tier

        Customers[LTV] >= 5000,  “Gold”,

        Customers[LTV] >= 1000,  “Silver”,

        “Standard”               — default for all others

    )

DAX Query View

Power BI Desktop’s DAX Query View is where comments become even more critical. Queries written here for analysis or debugging should be heavily annotated since they are often shared across teams.

/*

  Query: Top 10 Customers by Revenue — Last 90 Days

  Used for: Monthly executive review deck

  Context: Filters applied via CALCULATETABLE, not report slicers

*/

EVALUATE

TOPN(

    10,

    CALCULATETABLE(

        SUMMARIZECOLUMNS(

            Customers[CustomerName],

            “Revenue”, [Total Revenue]

        ),

        DATESINPERIOD(‘Date'[Date], TODAY(), -90, DAY)  — last 90 days

    ),

    [Revenue],

    DESC

)

📊 Stat: According to a Microsoft survey, 68% of Power BI report errors traced back to inherited models where the original logic was not documented. Commented measures cut troubleshooting time significantly.

Best Practices for DAX Comments That Actually Help

Not all comments are created equal. A bad comment creates as much confusion as no comment at all. Here are the practices that make your DAX documentation genuinely useful.

Comment the Why, Not the What

If your comment just restates what the code already says, it adds no value. Comment the intent and the reasoning.

— ❌ Weak comment: states the obvious

— Multiply quantity by price

Revenue = Sales[Quantity] * Sales[Price]

— ✅ Strong comment: explains the reasoning

— Using unit price at time of sale (not current price) per finance team requirement

Revenue = Sales[Quantity] * Sales[SaleDayPrice]

Add Headers to Complex Measures

For any measure longer than five lines, start with a block comment header. This gives anyone opening the measure an immediate orientation before reading a single line of code.

/*

  Measure: YTD Sales vs Target Gap

  Business Logic: Shows % gap between YTD actuals and annual target,

                  prorated to current date.

  Dependencies: [YTD Revenue], [Full Year Target]

  Last Modified: March 2024 — updated target table reference

*/

Use Comments to Disable Code During Testing

One of the most practical uses of comments is temporarily switching between two versions of a formula without deleting either. This makes testing and rollback far safer.

Revenue Adjusted =

    — Version A: include all transactions

    — [Total Revenue]

    — Version B: exclude refunds (currently active)

    CALCULATE([Total Revenue], Sales[TransactionType] = “Sale”)

Keep Comments Updated

A comment that describes logic that no longer exists is worse than no comment. When you change a measure, update the comment. Stale comments mislead future editors and erode trust in the documentation.

Build a simple habit: any time you update a formula, spend 60 seconds reviewing its comments. That is all it takes to keep your documentation accurate.

Standardize Across Your Team

If you work with others in the same Power BI model, agree on a comment format. Consistency matters more than any specific style. A simple standard — like always starting measures with a block comment header and using — for inline notes — means every person on your team instantly knows how to read any measure.

Research from the Software Engineering Institute found that teams using consistent documentation standards resolve code review issues 35% faster than those without standards.

Common Mistakes to Avoid

Forgetting Comments Don’t Display in Visuals

Comments are for the formula editor only. They never appear in report visuals, tooltips, or exported data. You can write freely without worrying about end-user impact.

Placing Comments Outside Valid DAX Context

Comments must be inside the DAX expression itself, not in field names, measure names, or table names. If you type — in the measure name field, it simply becomes part of the name.

Using Comments as a Substitute for Clean Code

Comments explain code — they don’t excuse messy code. If you need three paragraphs to explain what a line does, consider whether the line could be rewritten to be more readable first. Use clear VAR declarations alongside your comments for maximum clarity.

/*

  Using VAR declarations with comments for maximum readability

*/

Customer LTV Score =

VAR TotalRevenue = SUMX(Sales, Sales[Amount])          — lifetime revenue

VAR OrderCount   = COUNTROWS(Sales)                     — total orders placed

VAR AvgOrderVal  = DIVIDE(TotalRevenue, OrderCount, 0)  — AOV, 0 if no orders

RETURN

    TotalRevenue * 0.4 + AvgOrderVal * 0.3 + OrderCount * 0.3

Conclusion

Adding comments to your Power BI DAX code is one of the highest-ROI habits you can build as a report developer or analyst. It costs almost nothing in the moment and pays back every time someone — including future you — needs to understand, modify, or debug a measure.

The mechanics are simple: use — for quick inline notes and /* */ for block documentation. Apply them consistently, comment the why not just the what, and keep them updated when your logic changes.

Power BI has grown into a platform used by millions of professionals across every industry. The analysts who stand out are not just the ones who can write working DAX — they are the ones who write DAX that other people can maintain, trust, and build on.

Start with your next measure. Add one block comment header. Then do it again. That consistency, compounded over dozens of reports, is what separates maintainable Power BI models from ones that quietly become technical debt.