Alright, who else is getting absolutely *hammered* by Windsurf's compulsive need to narrate every single line of code like it's a nature documentary?
I'm all for helpful AI comments, but when I'm just iterating through a basic array or adding two numbers together, I don't need a paragraph explaining what a `for` loop is. It's polluting my PRs and making me look like I don't know what I'm doing.
My typical workflow:
1. I write a simple, obvious function.
2. Windsurf "helps" by adding a novel's worth of comments.
3. I spend more time deleting its commentary than I did writing the actual logic.
Example: I typed `const result = a + b;` and it gave me:
```javascript
// Calculate the sum of two numbers
// @param {number} a - The first operand
// @param {number} b - The second operand
// @returns {number} The total of a and b
const result = a + b; // Summation operation
```
I mean, come *on*. It's `a + b`. We learned this in grade school.
I've tried tweaking the instructions in the Windsurf config, but it's either too vague and gets ignored, or too restrictive and kills useful comments for complex logic. Has anyone found a sweet spot? A specific prompt that tells it to only comment on the *non-obvious* parts?
Or is this just the price we pay for having it generate boilerplate? I'd rather have no comments than these insulting ones.
benchmarks or bust
I've spent considerable time tuning Windsurf's behavior for my own data engineering workflows. You've hit on the core issue: it lacks a contextual understanding of what's "obvious" versus what merits explanation. The problem is that the system's default behavior is calibrated for a junior developer who needs the narrative, not for an expert writing straightforward data transformations.
Your config struggle is common. The key isn't in broad prohibitions like "don't comment," but in providing explicit positive instructions about what *should* be documented. I've had success with a layered approach in my workspace settings. I instruct it to only generate JSDoc/commentary when a function meets a complexity threshold, for example, lines of code > 5 or if it contains specific patterns like recursion or complex aggregations. I also explicitly list patterns to never comment on, like simple arithmetic operations, basic array `.map` or `.filter`, and standard BigQuery SQL clauses.
Try a prompt like: "Only generate JSDoc comments for functions or methods exceeding five logical lines. Never add inline comments for variable assignment, basic arithmetic, or common array operations (forEach, map, filter, reduce). Assume I understand fundamental language constructs."
It's not perfect, but it cuts down the noise by about 80% for me. You'll still get the occasional overreach, but it becomes manageable.
—KM
Oh man, you've just described my entire Monday. The "nature documentary" bit is spot on - I've seen it write a soliloquy for a basic API call that just fetches a user ID.
You've hit the exact frustration. The issue isn't the commenting, it's the total lack of context awareness. When I'm working in a well-trodden codebase full of similar patterns, adding a comment to a `map` function is just noise.
My workaround, and it's a bit of a hack, is to embed a strong "voice" directive right in my main workspace instructions. I tell it to assume the persona of a senior dev who comments *sparingly*, only for "why" not "what." I explicitly say things like "Assume I understand basic language constructs like for loops and addition. Only add JSDoc for functions with more than three parameters or that contain non-obvious business logic." It's not perfect, but it cuts down the chatter by about 70%.
The real battle scar? I had a client ask me why their junior devs were writing such patronizing code. Turns out Windsurf's verbose style had been accepted as a "best practice" and got baked into their linter config. Took a week to undo that cultural damage!
Implementation is 80% process, 20% tool.
Your example is the perfect case of over-calibration. The config tweaks fail because they're static rules trying to catch a dynamic problem.
You need to anchor it to your existing codebase. Open a few of your own files that represent clean, commented code the way you like it. Put a clear instruction in your workspace: "Comment density and style should match the patterns in [file X] and [file Y]. Assume the team knows standard library functions and basic operators."
It learns from what you show it. If your code is sparse, it'll copy that. Stops the nature documentary.
Totally agree with anchoring it to your existing code. That's the only thing that worked for me long-term.
The catch is you have to pick the right anchor files. I threw a huge, messy utility file at it once and the commenting got... chaotic. It needs a clean, consistent example.
I'd also add that this works best for the specific project you're in. It doesn't seem to carry over to new workspaces for me.
The "nature documentary" comment made me laugh, it's such a perfect description for that behavior. You're not alone.
The best trick I've found is to be brutally direct in your workspace instructions. Instead of saying "don't over-comment," try something like: "Only generate comments for code that is genuinely complex or non-obvious. Assume I am a senior developer and never explain basic language syntax, operators, or standard library functions."
It's still not perfect, but that kind of explicit framing about your assumed knowledge level helps a ton. It tends to cut out the soliloquies for `a + b`.
Keep it civil, keep it real.
You nailed it with "brutally direct." I've found that phrasing like "assume I am a senior developer" really does shift the tone. It's not just about cutting comments, it seems to make the suggestions more targeted overall, like it focuses on architectural hints instead of syntax explanations.
The only caveat is it can swing too far the other way in unfamiliar territory. If I'm working with a new library I've never used, sometimes I need that basic explanation and it won't give it. But for daily work in my own stack, it's perfect.
Always testing.
That's a really good point about it swinging too far the other way. I'm just starting with Windsurf, so I'm worried if I tell it to assume I'm senior, I'll miss the help when I actually do need it in a new library. Is there a way to switch that assumption on and off easily, or do you just keep editing the workspace instructions?