diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f3b1027e..f6730343 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -60,6 +60,7 @@ - [Initializing Maps](map-init.md) - [Format Strings outside Printf](printf-const.md) - [Naming Printf-style Functions](printf-name.md) + - [Format Strings Using `%q`](formatting-strings.md) - Patterns - [Test Tables](test-table.md) - [Functional Options](functional-option.md) diff --git a/src/formatting-strings.md b/src/formatting-strings.md new file mode 100644 index 00000000..3e9c7f59 --- /dev/null +++ b/src/formatting-strings.md @@ -0,0 +1,38 @@ +# Format Strings Using `%q` + +Whenever formatting messages that contain a string component via `fmt`, use `%q` instead of `%s`. This will wrap the specified string in quotes, helping it stand out from the rest of the error message. More importantly, if the string is empty, it will provide a more helpful error message. + + + + + +
BadGood
+ +```go +fmt.Errrof("file %s not found", filename) +// Prints the following: +// file myfile.go not found +// +// Or if the string is empty: +// file not found +``` + + + +```go +fmt.Errrof("file %q not found", filename) +// Prints the following: +// file "myfile.go" not found +// +// Or if the string is empty: +// file "" not found +``` + +
+ +This advice applies more generally to other contexts when reporting user-specified data, such as logging invalid usernames: + +```go +log.Printf("User %q does not exist", username) +// User "no_name" does not exist +``` diff --git a/style.md b/style.md index a8777d21..17217595 100644 --- a/style.md +++ b/style.md @@ -67,6 +67,7 @@ - [Initializing Maps](#initializing-maps) - [Format Strings outside Printf](#format-strings-outside-printf) - [Naming Printf-style Functions](#naming-printf-style-functions) + - [Format Strings Using `%q`](#format-strings-using-q) - [Patterns](#patterns) - [Test Tables](#test-tables) - [Functional Options](#functional-options) @@ -3584,6 +3585,45 @@ go vet -printfuncs=wrapf,statusf See also [go vet: Printf family check](https://kuzminva.wordpress.com/2017/11/07/go-vet-printf-family-check/). +### Format Strings Using `%q` + +Whenever formatting messages that contain a string component via `fmt`, use `%q` instead of `%s`. This will wrap the specified string in quotes, helping it stand out from the rest of the error message. More importantly, if the string is empty, it will provide a more helpful error message. + + + + + +
BadGood
+ +```go +fmt.Errrof("file %s not found", filename) +// Prints the following: +// file myfile.go not found +// +// Or if the string is empty: +// file not found +``` + + + +```go +fmt.Errrof("file %q not found", filename) +// Prints the following: +// file "myfile.go" not found +// +// Or if the string is empty: +// file "" not found +``` + +
+ +This advice applies more generally to other contexts when reporting user-specified data, such as logging invalid usernames: + +```go +log.Printf("User %q does not exist", username) +// User "no_name" does not exist +``` + ## Patterns ### Test Tables