mirror of
https://github.com/dart-lang/sdk
synced 2024-09-16 00:09:49 +00:00
One shared guide for diagnostics.
R=karlklose@google.com Review-Url: https://codereview.chromium.org/2718023003 .
This commit is contained in:
Peter von der Ahé
parent
64940df644
commit
3835ccf907
|
|
@ -2,64 +2,16 @@
|
|||
// for details. All rights reserved. Use of this source code is governed by a
|
||||
// BSD-style license that can be found in the LICENSE file.
|
||||
|
||||
/**
|
||||
* The messages in this file should meet the following guide lines:
|
||||
*
|
||||
* 1. The message should be a complete sentence starting with an uppercase
|
||||
* letter, and ending with a period.
|
||||
*
|
||||
* 2. Reserved words and embedded identifiers should be in single quotes, so
|
||||
* prefer double quotes for the complete message. For example, "The
|
||||
* class '#{className}' can't use 'super'." Notice that the word 'class' in the
|
||||
* preceding message is not quoted as it refers to the concept 'class', not the
|
||||
* reserved word. On the other hand, 'super' refers to the reserved word. Do
|
||||
* not quote 'null' and numeric literals.
|
||||
*
|
||||
* 3. Do not try to compose messages, as it can make translating them hard.
|
||||
*
|
||||
* 4. Try to keep the error messages short, but informative.
|
||||
*
|
||||
* 5. Use simple words and terminology, assume the reader of the message
|
||||
* doesn't have an advanced degree in math, and that English is not the
|
||||
* reader's native language. Do not assume any formal computer science
|
||||
* training. For example, do not use Latin abbreviations (prefer "that is" over
|
||||
* "i.e.", and "for example" over "e.g."). Also avoid phrases such as "if and
|
||||
* only if" and "iff", that level of precision is unnecessary.
|
||||
*
|
||||
* 6. Prefer contractions when they are in common use, for example, prefer
|
||||
* "can't" over "cannot". Using "cannot", "must not", "shall not", etc. is
|
||||
* off-putting to people new to programming.
|
||||
*
|
||||
* 7. Use common terminology, preferably from the Dart Language
|
||||
* Specification. This increases the user's chance of finding a good
|
||||
* explanation on the web.
|
||||
*
|
||||
* 8. Do not try to be cute or funny. It is extremely frustrating to work on a
|
||||
* product that crashes with a "tongue-in-cheek" message, especially if you did
|
||||
* not want to use this product to begin with.
|
||||
*
|
||||
* 9. Do not lie, that is, do not write error messages containing phrases like
|
||||
* "can't happen". If the user ever saw this message, it would be a
|
||||
* lie. Prefer messages like: "Internal error: This function should not be
|
||||
* called when 'x' is null.".
|
||||
*
|
||||
* 10. Prefer to not use imperative tone. That is, the message should not sound
|
||||
* accusing or like it is ordering the user around. The computer should
|
||||
* describe the problem, not criticize for violating the specification.
|
||||
*
|
||||
* Other things to keep in mind:
|
||||
*
|
||||
* An INFO message should always be preceded by a non-INFO message, and the
|
||||
* INFO messages are additional details about the preceding non-INFO
|
||||
* message. For example, consider duplicated elements. First report a WARNING
|
||||
* or ERROR about the duplicated element, and then report an INFO about the
|
||||
* location of the existing element.
|
||||
*
|
||||
* Generally, we want to provide messages that consists of three sentences:
|
||||
* 1. what is wrong, 2. why is it wrong, 3. how do I fix it. However, we
|
||||
* combine the first two in [template] and the last in [howToFix].
|
||||
*/
|
||||
|
||||
/// The messages in this file should follow the [Guide for Writing
|
||||
/// Diagnostics](../../../../front_end/lib/src/fasta/diagnostics.md).
|
||||
///
|
||||
/// Other things to keep in mind:
|
||||
///
|
||||
/// An INFO message should always be preceded by a non-INFO message, and the
|
||||
/// INFO messages are additional details about the preceding non-INFO
|
||||
/// message. For example, consider duplicated elements. First report a WARNING
|
||||
/// or ERROR about the duplicated element, and then report an INFO about the
|
||||
/// location of the existing element.
|
||||
library dart2js.messages;
|
||||
|
||||
import 'package:front_end/src/fasta/scanner.dart' show ErrorToken, Token;
|
||||
|
|
|
|||
|
|
@ -2,62 +2,14 @@
|
|||
// for details. All rights reserved. Use of this source code is governed by a
|
||||
// BSD-style license that can be found in the LICENSE file.
|
||||
|
||||
// An update to this file must be followed by regenerating the corresponding
|
||||
// json, dart2js and analyzer file. Use `publish.dart` in the bin directory.
|
||||
//
|
||||
// Every message in this file must have an id. Use `message_id.dart` in the
|
||||
// bin directory to generate a fresh one.
|
||||
|
||||
// The messages in this file should meet the following guide lines:
|
||||
//
|
||||
// 1. The message should be a complete sentence starting with an uppercase
|
||||
// letter, and ending with a period.
|
||||
//
|
||||
// 2. Reserved words and embedded identifiers should be in single quotes, so
|
||||
// prefer double quotes for the complete message. For example, "The
|
||||
// class '#{className}' can't use 'super'." Notice that the word 'class' in the
|
||||
// preceding message is not quoted as it refers to the concept 'class', not the
|
||||
// reserved word. On the other hand, 'super' refers to the reserved word. Do
|
||||
// not quote 'null' and numeric literals.
|
||||
//
|
||||
// 3. Do not try to compose messages, as it can make translating them hard.
|
||||
//
|
||||
// 4. Try to keep the error messages short, but informative.
|
||||
//
|
||||
// 5. Use simple words and terminology, assume the reader of the message
|
||||
// doesn't have an advanced degree in math, and that English is not the
|
||||
// reader's native language. Do not assume any formal computer science
|
||||
// training. For example, do not use Latin abbreviations (prefer "that is" over
|
||||
// "i.e.", and "for example" over "e.g."). Also avoid phrases such as "if and
|
||||
// only if" and "iff", that level of precision is unnecessary.
|
||||
//
|
||||
// 6. Prefer contractions when they are in common use, for example, prefer
|
||||
// "can't" over "cannot". Using "cannot", "must not", "shall not", etc. is
|
||||
// off-putting to people new to programming.
|
||||
//
|
||||
// 7. Use common terminology, preferably from the Dart Language
|
||||
// Specification. This increases the user's chance of finding a good
|
||||
// explanation on the web.
|
||||
//
|
||||
// 8. Do not try to be cute or funny. It is extremely frustrating to work on a
|
||||
// product that crashes with a "tongue-in-cheek" message, especially if you did
|
||||
// not want to use this product to begin with.
|
||||
//
|
||||
// 9. Do not lie, that is, do not write error messages containing phrases like
|
||||
// "can't happen". If the user ever saw this message, it would be a
|
||||
// lie. Prefer messages like: "Internal error: This function should not be
|
||||
// called when 'x' is null.".
|
||||
//
|
||||
// 10. Prefer to not use imperative tone. That is, the message should not sound
|
||||
// accusing or like it is ordering the user around. The computer should
|
||||
// describe the problem, not criticize for violating the specification.
|
||||
//
|
||||
// Other things to keep in mind:
|
||||
//
|
||||
// Generally, we want to provide messages that consists of three sentences:
|
||||
// 1. what is wrong, 2. why is it wrong, 3. how do I fix it. However, we
|
||||
// combine the first two in [template] and the last in [howToFix].
|
||||
|
||||
/// An update to this file must be followed by regenerating the corresponding
|
||||
/// json, dart2js and analyzer file. Use `publish.dart` in the bin directory.
|
||||
///
|
||||
/// Every message in this file must have an id. Use `message_id.dart` in the
|
||||
/// bin directory to generate a fresh one.
|
||||
///
|
||||
/// The messages in this file should follow the [Guide for Writing
|
||||
/// Diagnostics](../../front_end/lib/src/fasta/diagnostics.md).
|
||||
import 'dart:convert';
|
||||
|
||||
/// Encodes the category of the message.
|
||||
|
|
|
|||
|
|
@ -2,65 +2,10 @@
|
|||
// for details. All rights reserved. Use of this source code is governed by a
|
||||
// BSD-style license that can be found in the LICENSE file.
|
||||
|
||||
/**
|
||||
* An error code associated with an [AnalysisError].
|
||||
*
|
||||
* Generally, we want to provide messages that consist of three sentences. From
|
||||
* the user's perspective these sentences should explain:
|
||||
*
|
||||
* 1. what is wrong,
|
||||
* 2. why is it wrong, and
|
||||
* 3. how do I fix it.
|
||||
*
|
||||
* However, we combine the first two in the [message] and the last in the
|
||||
* [correction].
|
||||
*
|
||||
* When composing messages (including correction messages) keep the following
|
||||
* guidelines in mind.
|
||||
*
|
||||
* 1. The message should be a complete sentence starting with an uppercase
|
||||
* letter, and ending with a period.
|
||||
*
|
||||
* 2. Reserved words and embedded identifiers should be in single quotes, so
|
||||
* prefer double quotes for the complete message. For example,
|
||||
* ```
|
||||
* "The class '{0}' can't use 'super'."
|
||||
* ```
|
||||
* Notice that the word 'class' in the preceding message is not quoted as it
|
||||
* refers to the concept 'class', not the reserved word. On the other hand,
|
||||
* 'super' refers to the reserved word. Do not quote 'null' and numeric literals.
|
||||
*
|
||||
* 3. Do not try to compose messages, as it can make translating them hard.
|
||||
*
|
||||
* 4. Try to keep the error messages short, but informative.
|
||||
*
|
||||
* 5. Use simple words and terminology, assume the reader of the message doesn't
|
||||
* have an advanced degree in math, and that English is not the reader's native
|
||||
* language. Do not assume any formal computer science training. For example, do
|
||||
* not use Latin abbreviations (prefer "that is" over "i.e.", and "for example"
|
||||
* over "e.g."). Also avoid phrases such as "if and only if" and "iff"; that
|
||||
* level of precision is unnecessary.
|
||||
*
|
||||
* 6. Prefer contractions when they are in common use, for example, prefer
|
||||
* "can't" over "cannot". Using "cannot", "must not", "shall not", etc. is
|
||||
* off-putting to people new to programming.
|
||||
*
|
||||
* 7. Use common terminology, preferably from the Dart Language Specification.
|
||||
* This increases the user's chance of finding a good explanation on the web.
|
||||
*
|
||||
* 8. Do not try to be cute or funny. It is extremely frustrating to work on a
|
||||
* product that crashes with a "tongue-in-cheek" message, especially if you did
|
||||
* not want to use this product to begin with.
|
||||
*
|
||||
* 9. Do not lie, that is, do not write error messages containing phrases like
|
||||
* "can't happen". If the user ever saw this message, it would be a lie. Prefer
|
||||
* messages like: "Internal error: This function should not be called when 'x'
|
||||
* is null.".
|
||||
*
|
||||
* 10. Prefer to not use the imperative tone. That is, the message should not
|
||||
* sound accusing or like it is ordering the user around. The computer should
|
||||
* describe the problem, not criticize the user for violating the specification.
|
||||
*/
|
||||
/// An error code associated with an [AnalysisError].
|
||||
///
|
||||
/// Generally, messages should follow the [Guide for Writing
|
||||
/// Diagnostics](../fasta/diagnostics.md).
|
||||
abstract class ErrorCode {
|
||||
/**
|
||||
* The name of the error code.
|
||||
|
|
|
|||
85
pkg/front_end/lib/src/fasta/diagnostics.md
Normal file
85
pkg/front_end/lib/src/fasta/diagnostics.md
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
<!--
|
||||
-- Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
|
||||
-- for details. All rights reserved. Use of this source code is governed by a
|
||||
-- BSD-style license that can be found in the LICENSE file.
|
||||
-->
|
||||
|
||||
# Guide for Writing Diagnostics
|
||||
|
||||
## The Rule of 3
|
||||
|
||||
A great message conveys the following three things:
|
||||
|
||||
1. What is wrong?
|
||||
2. Why is it wrong?
|
||||
3. How do I fix it?
|
||||
|
||||
## Complete Sentences
|
||||
|
||||
The message should be a complete sentence starting with an uppercase letter, and ending with a period. The message shouldn't start with "error:", "warning:", and so on.
|
||||
|
||||
## Use Single Quotes in Messages
|
||||
|
||||
Reserved words and embedded identifiers should be in single quotes as we have found those are ignored by search engines whereas double quotes can have meaning in search engines.
|
||||
|
||||
In practice, this means that messages written in Dart source code should be written in double quotes, which makes it easier to use single quotes inside the message. For example:
|
||||
|
||||
"The class '#{className}' can't use 'super'."
|
||||
|
||||
Notice that the word "class" in the preceding message is not quoted as it refers to the concept *class*, not the reserved word. On the other hand, `'super'` refers to the reserved word. Do not quote `null` and numeric literals.
|
||||
|
||||
Also, remember that the output isn't Markdown, so be careful to not use Markdown syntax. In particular, do not use <code>\`</code> (backtick) for quoting.
|
||||
|
||||
## Avoid Composing Messages Programmatically
|
||||
|
||||
Composing messages programmatically can make it hard to translate them.
|
||||
|
||||
## Keep Message Short
|
||||
|
||||
Try to keep the error messages short, but informative.
|
||||
|
||||
## Simple Words and Terminology
|
||||
|
||||
Use simple words and terminology.
|
||||
|
||||
Do not assume that
|
||||
|
||||
* English is the reader's native language,
|
||||
* the reader has any formal computer science training, or
|
||||
* the reader has an advanced degree in mathematics.
|
||||
|
||||
Similarly, do not use Latin abbreviations (prefer "that is" over "i.e.," and "for example" over "e.g."). Also avoid phrases such as "if and only if" and "iff"; that level of precision is unnecessary.
|
||||
|
||||
## Prefer Contractions
|
||||
|
||||
Prefer contractions when they are in common use, for example, prefer "can't" over "cannot". Using "cannot", "must not", "shall not", and so on, is off-putting to people new to programming.
|
||||
|
||||
## Use Common Terminology
|
||||
|
||||
Use common terminology, for example, from the [Dart Language Specification](https://www.dartlang.org/guides/language/spec). This increases the user's chance of finding a good explanation on the web. Do not invent your own terminology or obscure terminology. For example, "rune" isn't a great way to describe a Unicode code point (albeit, code points and code units can be confusing).
|
||||
|
||||
## Don't Try to be Cute or Funny
|
||||
|
||||
It is extremely frustrating to work on a product that crashes with a tongue-in-cheek message, especially if you did not want to use this product to begin with.
|
||||
|
||||
## Things Can Happen
|
||||
|
||||
Do not lie, that is, do not write error messages containing phrases like "can't happen". If the user ever saw this message, it would be a lie. Prefer messages like:
|
||||
|
||||
"Internal error: This function shouldn't be called when 'x' is null.".
|
||||
|
||||
## Avoid Imperative Tone
|
||||
|
||||
Prefer to not use imperative tone. That is, the message should not sound accusing or like it is ordering the user around. The computer should describe the problem, not criticize for violating the specification. Often, it's as simple as adding the word "try". For example:
|
||||
|
||||
"Try changing the return type." // Preferred.
|
||||
|
||||
Versus:
|
||||
|
||||
"Change the return type." // Avoid this.
|
||||
|
||||
Notice that the style of the language in which this guide is written, is mostly imperative. That's not an example to follow when writing diagnostics.
|
||||
|
||||
## Other Resources
|
||||
|
||||
One language and community where good error messages have been discussed intensively is [Elm](http://elm-lang.org/blog/compiler-errors-for-humans).
|
||||
Loading…
Reference in a new issue