Bikeshedding: Error messages and comments

[efaulhaber]

I'm sorry for the major bikeshedding, but let's settle this once and for all to avoid future bikeshedding in PRs.

How do we want error messages to look like?

1. Should the first word be capitalized or not?
2. Punctuation: When the message is just one sentence or a sentence fragment, should we end it with a period or exclamation mark, or no punctuation?

In Julia, sentence fragments starting with lowercase and no punctuation seem to be preferred:

julia> Dict{1,2 ,3 }
ERROR: too many parameters for type

julia> if 4
       end
ERROR: TypeError: non-boolean (Int64) used in boolean context

julia> sqrt(-1)
ERROR: DomainError with -1.0:
sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
Stacktrace:
 [1-2] ⋮ internal
     @ Base.Math, Unknown
   [3] sqrt(x::Int64)
     @ Base.Math ./math.jl:1372
Use `err` to retrieve the full stack trace.

julia> f()
ERROR: UndefVarError: f not defined

julia> Int(1e100)
ERROR: InexactError: Int64(1.0e100)
Stacktrace:
   [1] Int64(x::Float64)
     @ Base ./float.jl:788

julia> x = []; x[1]
ERROR: BoundsError: attempt to access 0-element Vector{Any} at index [1]
Stacktrace:
   [1] getindex(A::Vector{Any}, i1::Int64)
     @ Base ./array.jl:924

But not consistent outside of base:

julia> using sfdljoisdf
ERROR: ArgumentError: Package sfdljoisdf not found in current path.
- Run `import Pkg; Pkg.add("sfdljoisdf")` to install the sfdljoisdf package.

Same for comments, while we're at it:

1. Should comments start with a lowercase letter?
2. Should sentence fragments end with a period?
3. Should full sentences end with a period? (Of course, when the comment consists of multiple sentences, we end all of them with a period.)

My personal opinion (when I say no opinion, I still want us to pick one and use it consistently):

• No opinion about starting error messages with lower or upper case.
• No opinion about ending without punctuation or with a period, but I am strongly against exclamation marks (too aggressive).
• I prefer starting comments with an uppercase letter.
• I prefer no punctuation for comments unless there are multiple sentences, in which case I end all of them with a period. (I prefer not to add periods after links to avoid breaking the link when copying it.)

[LasNikas]

I would like to have the same convention for comments and for log events.

1. Should comments start with a lowercase letter?

Only for sentence fragments but not for full sentences (i.e. capitalize when sentence ends with punctuation).

2. Should sentence fragments end with a period?

Fragments not.

3. Should full sentences end with a period? (Of course, when the comment consists of multiple sentences, we end all of them with a period.)

Full and multiple sentences, yes

[efaulhaber]

1.Should comments start with a lowercase letter?

Only for sentence fragments but not for full sentences (i.e. capitalize when sentence ends with punctuation).

This will make everything look very inconsistent, IMO.

2. Should sentence fragments end with a period?

Fragments not.

I'm fine with that, although it leaves a lot of space for interpretation.

# Compute things

is a full sentence, but one might not want to put a period there and consider it a fragment because it's so short.

What do you think about period vs exclamation mark in error messages?

[LasNikas]

This will make everything look very inconsistent, IMO.

Then capitalize only for comments but not for log events?

I'm fine with that, although it leaves a lot of space for interpretation.

fair! So, then only punctuation for multiple sentences.

What do you think about period vs exclamation mark in error messages?

I share your opinion on this.

[efaulhaber]

Okay, so do we all agree on the following?

1. Error descriptions always start with a lowercase letter.
2. Comments always start with an uppercase letter.
3. Both comments and error descriptions have no punctuation unless there are multiple sentences or it's a multiline comment.
4. No exclamation mark in error messages. Use periods with multiple sentences.
5. Warnings/infos start always start with an uppercase letter.

I think the last point is most consistent with the errors, since in error messages, the first letter after "ERROR:" also starts with an uppercase letter (that's the error type):

julia> x = []; x[1]
ERROR: BoundsError: attempt to access 0-element Vector{Any} at index [1]
Stacktrace:
   [1] getindex(A::Vector{Any}, i1::Int64)
     @ Base ./array.jl:924

julia> @warn "Particles are overlapping"
┌ Warning: Particles are overlapping
└ @ Main REPL[37]:1