proposal: testing: add magic //go:cover ignore comment

[earthboundkid]

Problem

The Go coverage tool is very useful, but there's no way to mark a line as not needing coverage. It is common to add panic("unreachable") in place where one expects code never to run unless there is a programmatic error. These lines show up in code coverage output as untested and must be manually inspected in order to be noted that they can be ignored and don't need to be tested.

Proposal

If a line is prefaced by //go:cover ignore the following expression or block will be marked as "ignored".

// some switch ...
case 1:
  return "1"
//go:cover ignore
default: // this line and the next will be marked as ignored
   panic("unreachable")
// ...

$ go test -coverprofile=coverage.out
PASS
coverage: 42% of statements (2% ignored)
ok      size    0.030s

In the HTML output of the cover tool, ignored lines should be marked with yellow. If an ignored line is covered during a test, it should be reported as "ignored but covered" and marked in purple for investigation of whether a programmatic error has taken place.

Cf #31280

[seankhliao]

same as #34639

[randall77]

See also #12504

[earthboundkid]

Based on prior comments, Rob Pike is opposed to magic comments to control the cover tool. That makes sense, but if there's no knob for controlling the cover tool, it would be good if the tool had some way of detecting and ignoring panic("unreachable") lines on its own. Maybe panic("unreachable") should be its own magic comment?

[Jorropo]

Maybe panic("unreachable") should be its own magic comment?

The discoverability of that feature for new users sounds really low.

I think, a builtin (or somewhere in the std):

func unreachable() {
  panic("unreachable")
}

And the magic comment being unreachable() is better.

This is a feature other modern languages integrates, for example see in rust or GCC & Clang extensions.

[earthboundkid]

See #30582 for an unreachable in the standard library.

[breml]

I understand, that Rob Pike has a strong voice, but what is about the community?

As mentioned in #31280 (comment), a substantial part of the community already adopted tools, that work with magic comments to handle false positives. The //go:cover ignore comment would do a similar thing and I would not be surprised, if the same parts of the community would adopt this feature.

If such a magic comment is introduced, nobody is required to use it and the Go team can forbid to use it in the Go standard library, the Go tooling, etc. if they really wish to do this.

[ianlancetaylor]

If we're never going to use them in the Go standard library and tooling, then it doesn't seem too hard to me to wrap the Go coverage tool with a wrapper that looks for the comments itself.

If we add direct support in the Go coverage tool, we will be regularly rejecting patches to add them to the Go standard library.

[rsc]

I'm not sure why this has to be part of cover. If you have something that reports the uncovered lines, couldn't it filter them out instead? In general we're thinking about redoing the way cover works to be more inside the compiler, and I'd rather not have the compiler need to introduce per-basic-block magic comments as a concept.

[rsc]

I wrote this tool a while back: https://pkg.go.dev/rsc.io/tmp/uncover.
You could imagine doing something similar and filtering in that tool instead.
The only time this would need to be in cover is to affect the reported percentage.
Maybe we should remove the reported percentages because people focus too much on them?

[Jorropo]

See #30582 for an unreachable in the standard library.

This seems to be a different proposal.
It seems to care about performance and this would be a compiler hint, with an unsafe mode that let the compiler prune unreachable branches.

What I propose is functionally equivalement to panic("unreachable") except the coverage tool would understand it (not like the Gcc builtin then, I've removed that part).

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[rsc]

What I propose is functionally equivalement to panic("unreachable") except the coverage tool would understand it

Why is it important for the coverage tool to "understand it"?
Are people focusing too much on the percentages?