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

wiki: CodeReviewComments should have better example for lowercasing error strings #49196

Open
twocs opened this issue Oct 28, 2021 · 2 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@twocs
Copy link

twocs commented Oct 28, 2021

In the Readme https://github.com/golang/go/wiki/CodeReviewComments#error-strings it states:

Error Strings
Error strings should not be capitalized (unless beginning with proper nouns or acronyms) or end with punctuation, since they are usually printed following other context. That is, use fmt.Errorf("something bad") not fmt.Errorf("Something bad"), so that log.Printf("Reading %s: %v", filename, err) formats without a spurious capital letter mid-message. This does not apply to logging, which is implicitly line-oriented and not combined inside other messages.

The example is bad and the justification given is weak. For example, a sentence case error message parsed by log.Printf("Reading %s: %v", filename, err) might produce the following: Reading file.txt: Something bad. This is perfectly fine English. Programming style conventionally follows American usage, "A colon is not normally followed by a capital letter in British usage, though American usage often prefers to use a capital." Thus, there is no problem presented in the example given, and in fact, American usage should by rights protest the lack of the capital letter. Surely there is a better example that should be given for this rule!

Furthermore, I think it much more likely that the reason for requiring error messages to be lowercase is to avoid the issues that arise if mixed case error messages are acceptable. For example, if one error message is Something bad and another is something bad, an issue occurs that the error messages are different but likely had the same intended meaning. By requiring the case to be one way and not the other, we reduce the risk of accidentally creating new messages.

In conclusion, the rule is good. We should continue to start error messages with lowercase letters, but we should drop these bad examples and (in my opinion) post hoc excuses to justify the rule.

@seankhliao seankhliao changed the title The example for lowercase error messages is poor quality doc: CodeReviewComments should have better example for lowercasing error strings Oct 28, 2021
@seankhliao seankhliao added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Oct 28, 2021
@seankhliao
Copy link
Member

cc @ianlancetaylor

@ianlancetaylor
Copy link
Contributor

I was taught (in an American school) that the letter after a colon is capitalized only if it starts a complete sentence.

@seankhliao seankhliao added this to the Unreleased milestone Aug 20, 2022
@seankhliao seankhliao changed the title doc: CodeReviewComments should have better example for lowercasing error strings wiki: CodeReviewComments should have better example for lowercasing error strings Aug 20, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

4 participants