Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

all: create a special annotation to indicate that a function panics #44056

Open
pjebs opened this issue Feb 1, 2021 · 6 comments
Open

all: create a special annotation to indicate that a function panics #44056

pjebs opened this issue Feb 1, 2021 · 6 comments

Comments

@pjebs
Copy link
Contributor

@pjebs pjebs commented Feb 1, 2021

It would be good for a special comment tag or something to document that a function potentially panics.

Godoc would detect the tag and display a special label or ⚠️ symbol .

or

🅿 🅟

@davecheney
Copy link
Contributor

@davecheney davecheney commented Feb 1, 2021

What about methods on interfaces?

@pjebs
Copy link
Contributor Author

@pjebs pjebs commented Feb 1, 2021

The special comment tag can apply to functions in an interface too.

However, any exported object that implements a function from the interface can also document panics.

@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Feb 1, 2021

Many functions can panic if invalid input is passed.

@pjebs
Copy link
Contributor Author

@pjebs pjebs commented Feb 1, 2021

They should all be labeled as potentially panicing.

The rationale is that Go encourages you to do things concurrently in separate goroutines.
Webservers, even with Recovery middleware, can't protect against panics in separate goroutines.

This is very dangerous because it's easy to forget that a function may panic. Labelling it as such is the least we can do, before it brings down the entire server.

@fzipp
Copy link
Contributor

@fzipp fzipp commented Feb 1, 2021

One nice property of Go's doc comments is that they are not schematised, and a nice property of godoc & Co. is that the presentation is clutter free. A panic should be simply mentioned in the text as a sentence, just like anything else noteworthy should be mentioned in the text.

@seankhliao
Copy link
Contributor

@seankhliao seankhliao commented Feb 2, 2021

I don't think this is a good idea if it's done voluntarily and manually as this wouldn't cover the myriad of ways things can panic and would lead users into a false sense of security when they don't see the marker.

@dmitshur dmitshur changed the title Documenting that a function panics all: create a special annotation to indicate that a function panics Feb 8, 2021
@dmitshur dmitshur added this to the Backlog milestone Feb 8, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants