Document throwInternalError

pkg/fletchc/lib/src/diagnostic.dart

 // Copyright (c) 2015, the Fletch 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.md file.
 
 library fletchc.diagnostic;
 
 import 'messages.dart' show
     DiagnosticKind,
     getMessage;
 
@@ skipping 106 matching lines @@
         Target target = value;
         // TODO(ahe): Improve this conversion.
         stringValue = target.toString();
         break;
     }
     result[parameter.name] = stringValue;
   });
   return result;
 }
 
+/// Throw an internal error that will be recorded as a compiler crash.
+///
+/// In general, assume, no matter how unlikely, that [message] may be read by a
+/// user (that is, a developer using Fletch). For this reason, try to:
+///
+/// * Avoid phrases that can be interpreted as blaming the user (all error
+///   messages should state what is wrong, in a way that doesn't assign blame).
+///
+/// * Avoid being cute or funny (there's nothing more frustrating than being
+///   affected by a bug and see a cute or funny message, especially if it
+///   happens a lot).
+///
+/// * Avoid phrases like "unreachable", "can't happen", "shouldn't happen",
+///   "shouldn't be called", simply because it is wrong: it did happen. In most
+///   cases a factual message would be "unimplemented", "unhandled case",
+///   etc. Remember that the stacktrace will pinpoint the exact location of the
+///   problem, so no need to repeat a method name.
 void throwInternalError(String message) {
   throw new InputError(
       DiagnosticKind.internalError,
       <DiagnosticParameter, dynamic>{DiagnosticParameter.message: message});
 }
 
 void throwFatalError(
     DiagnosticKind kind,
     {String message,
      ResolvedVerb verb,
@@ skipping 16 matching lines @@
     arguments[DiagnosticParameter.target] = target;
   }
   if (address != null) {
     arguments[DiagnosticParameter.address] = address;
   }
   if (userInput != null) {
     arguments[DiagnosticParameter.userInput] = address;
   }
   throw new InputError(kind, arguments);
 }