[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines

[GitBox <gi...@apache.org>]

dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615336105



##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+  weight: 5
+  show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
+
+-   **Who** encountered the problem?
+-   **What** was the problem?
+-   **When** did the problem happen?
+-   **Why** did the problem happen?
+-   **How** can the problem be solved?
+
+The context provided by exceptions can help answer **who** (usually the
+user), **when** (usually included in the log via <code>log4j</code>), and **where**
+(usually included in the stack trace). However, these answers alone are
+often insufficient for the user to solve the problem. An error message
+that answers the remaining questions
+--- **what**, **why**, and **how** --- minimizes user frustration.
+
+#### Explicitly answer What, Why and How
+
+In many cases, the error message should explicitly answer **what**,
+**why**, and **how**.
+
+##### Example 1
+
+<code style="white-space:normal">
+  <a href="https://github.com/apache/spark/blob/569fb133d09e24e4ed56ed7efff641512d98b01b/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L160">
+    Unable to generate an encoder for inner class {} without access to the
+    scope that this class was defined in. Try moving this class out of its
+    parent class.
+  </a>
+</code>
+
+-   **What:** Unable to generate encoder inner class.
+-   **Why:** Did not have access to the scope that the class was defined
+    in.
+-   **How:** Try moving this class out of its parent class.
+
+##### Example 2
+
+If the proposed fix (**how**) feels arbitrary, providing an explanation
+for **why** the error occurred can reduce user frustration.
+
+<code style="white-space:normal">
+  <a href="https://github.com/apache/spark/blob/03dd33cc982ebb3de4354274ac49da31521b8195/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L498">
+    <span style="background-color: #ffcccc">Unsupported</span> function name {}.
+  </a>
+</code>
+
+-   **What:** Unsupported function name.
+-   **Why:** Unclear.
+-   **How:** Unclear.
+
+**After**

Review comment:
       It seems that we need to add a matching `**Before**`.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org