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

doc: make it more explicit where print and println can be used #48029

Open
rakyll opened this issue Aug 28, 2021 · 4 comments
Open

doc: make it more explicit where print and println can be used #48029

rakyll opened this issue Aug 28, 2021 · 4 comments
Labels
Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone

Comments

@rakyll
Copy link
Contributor

rakyll commented Aug 28, 2021

Specification's "Bootstrapping" section mentions print and println can be removed from the language anytime, https://golang.org/ref/spec#Bootstrapping. But the section doesn't explain that they can be used in rare situations where importing fmt is not possible and it's otherwise better not to rely on them.

The community is confused due to existing reference code, examples and autogenerated code (by products like GitHub's Copilot) using print and println statements. The current wording in the section doesn't appear to be strong enough to discourage them and it might be useful to give more concrete reasons where the built in functions are suited to help them make the correct judgement.

@rakyll rakyll changed the title doc: make it more explicit where built-in functions can be used doc: make it more explicit where print and println can be used Aug 28, 2021
@robpike
Copy link
Contributor

robpike commented Aug 28, 2021

I like the vagueness of the specification. They are for bootstrapping and have weak guarantees, so they are use-at-your-own-risk, as stated in the specification. The spec doesn't even state where they send the data (stdout? stderr?) and that's fine.

You shouldn't use them in production code, they are not fully portable, but they can be handy sometimes.

@deadprogram
Copy link

Just to mention it, we do need them for TinyGo especially when using in devices with very limited memory footprint such as the Arduino boards that only have 8-bit processors.

@dmitshur
Copy link
Contributor

dmitshur commented Aug 28, 2021

I understand the Go language specification is vague for the reasons Rob suggested, allowing different implementations of the Go language to implement them as most appropriate.

The behavior of Go’s implementation of these builtin functions is documented via godoc (https://golang.org/pkg/builtin#print):

The print built-in function formats its arguments in an implementation-specific way and writes the result to standard error. Print is useful for bootstrapping and debugging; it is not guaranteed to stay in the language.

Notably, it mentions that result is written to stderr, but exact formatting isn’t described in detail. (GopherJS’ implementation of print sends data to the browser console via console.log, which is permitted by the current spec.)

The fmt.Print docs and the Printing section describe formatting in great detail, hopefully allowing users to select based on their needs:

Print formats using the default formats for its operands and writes to standard output. Spaces are added between operands when neither is a string. It returns the number of bytes written and any write error encountered.

Perhaps there’s room for improvement somewhere, but I wanted to mention that the Go specification isn’t the only place users can refer to for learning about the behavior of print.

@seankhliao
Copy link
Member

Maybe this is better suited for CodeReviewComments rather than spec?

@cherrymui cherrymui added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Aug 30, 2021
@cherrymui cherrymui added this to the Backlog milestone Aug 30, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Development

No branches or pull requests

7 participants