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

refactor(errors): improve error messages #390

Merged

Conversation

stefanblaginov
Copy link
Contributor

@stefanblaginov stefanblaginov commented Mar 4, 2022

Closes #389

Changes

  • Terms are surrounded by double quotation marks, common to US English. Terms are all words that represent code, parts or snippets of Concerto and differ from the complementing explanatory text in the error message.
  • Full stops at the end of error message (detail) sentences have been added in order to provide a consistent error format. The reasoning behind this is that error messages are proper sentences, rather than just titles. Some discussion surrounding this:
    https://ux.stackexchange.com/questions/18671/periods-at-the-end-of-a-sentence-in-alert-message
    https://stackoverflow.com/questions/1136829/do-you-end-your-exception-messages-with-a-period
  • Replace occurrences of "super type" with "supertype", which seems to be widely used.
  • Improved consistency when it comes to terms surrounded by parentheses.
  • Forego the "telegraph-ese" style of messages and use grammatical articles.
  • Remove sentence ambiguity. The last thing that developers would like to do while debugging is do meaning guesswork.
  • Some tests were improved to include more concrete error text checks (rather than partial regex matching) and to have a more useful failed test output.

Flags

Code dependant on parsing concerto-core error messages is likely to break from this change.

Author Checklist

  • Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
  • Vital features and changes captured in unit and/or integration tests
  • Commits messages follow AP format
  • Extend the documentation, if necessary
  • Merging to master from fork:branchname

@stefanblaginov stefanblaginov force-pushed the sb-improve-error-messages branch from 803ce7f to 80a9674 Compare March 4, 2022 12:24
Copy link
Member

@jeromesimeon jeromesimeon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good @stefanblaginov !

I've placed a couple of comments for things that should be doublechecked.

Also, I feel there is more work we should be doing on error messages:

  1. Check that all those errors are actually used, some of them may be obsolete and could be removed
  2. Check for use of other errors that aren't listed in the message/en.json and use a different approach e.g., throw new Error("This is some error which is thrown by hand")

So I wouldn't mind leaving your issue open and listing those are additional work that would be useful to do.


// set model to a Boolean
cObject.model = true;
( function() {serializer.toJSON(cObject);}).should.throw(/.+expected type String/);
( function() {serializer.toJSON(cObject);}).should.throw('Model violation in the "org.acme.Vehicle#CAR_123" instance. The field "model" has a value of "true" (type of value: "boolean"). Expected type of value: "String".');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Am I the only one finding those changes confusing, surely "1" is a String!

@@ -233,7 +233,7 @@ describe('ObjectValidator', function () {

(function () {
objectValidator.visit(concerto.getTypeDeclaration(data), parameters);
}).should.throw(/Instance undefined has property previousOwners with type undefined that is not derived from test.Person\[\]/);
}).should.throw('Instance "undefined" has a property "previousOwners" with type "undefined" that is not derived from "test.Person[]".');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if the undefined here is a bug? the sentence doesn't read quite right. Could we double check?

@@ -264,7 +264,7 @@ describe('ObjectValidator', function () {
parameters.stack = new TypedStack(data);
(function () {
objectValidator.visit(concerto.getTypeDeclaration(data), parameters);
}).should.throw(/expected a Relationship/);
}).should.throw('Model violation in the "undefined" instance. Class "test.Person" has a value of "[object Object]". Expected a "Relationship".');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if the undefined here is a bug? the sentence doesn't read quite right. Could we double check?

@stefanblaginov stefanblaginov force-pushed the sb-improve-error-messages branch from 80a9674 to f45cadc Compare March 14, 2022 13:22
@stefanblaginov stefanblaginov force-pushed the sb-improve-error-messages branch from 3e0c82e to 219cbf6 Compare April 1, 2022 13:41
@mttrbrts mttrbrts merged commit 57afa8b into accordproject:master Apr 1, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Error messages need consistency improvements
3 participants