Consistent error messages in all modules

[micnic]

Based on PR #892 I want to propose to define some general rules for writing error messages. For the beginning, I propose the following rules:

• Capitalized first word at the beginning of the message

TypeError: First argument should be a string or buffer

• Quoted variable name

Error: "name" argument is required

• Verbose message text

Error: Bad argument // instead of "bad arg" which is used now in SyncWriteStream.prototype.write
RangeError: "n" should be less than or equal to "kMaxLength"

• Consistent usage of "should" vs "must" as mentioned by @timoxley Consistent error messages in all modules #892 (comment) to follow https://tools.ietf.org/html/rfc2119

cc @iojs/collaborators

[tellnes]

+1

[mscdex]

+1

[Fishrock123]

What about ending periods?

I kinda prefer backticks to quotations for code references, but that's probably just because of markdown.

[micnic]

@Fishrock123, I think periods are irrelevant in understanding the message of the error

another thing that I missed: error message length limit ~60 chars

[mscdex]

@micnic How would that work for error messages that contain dynamic content, such as filenames?

[micnic]

@mscdex, for error messages with some urls or filenames attached it will not work :) but at least we should take in count this while using some messages like the following ones:

'"localAddress" argument must be a valid IP: ' + localAddress
'"port" argument should be > 0 and < 65536: ' + port
'Parameter "pathObject" must be an object, not ' + typeof pathObject

[silverwind]

+1

Do we have a file where we write down rules such as this? CONTRIBUTING.md doesn't seem to contain anything in regards to code style (and error style). Maybe we should add a STYLE.md or an section to CONTRIBUTING.md.

cc: @mikeal

[chrisdickinson]

We don't really have a great place at present to record these sorts of decisions. It would be cool to start a doc/internal directory for internal development guidelines & documentation, though.

[brendanashworth]

We definitely need something like that. +1

[yosuke-furukawa]

+1 !

[cjihrig]

Closing as this landed in 20285ad