Reading Stack Traces #87
Conversation
|
Thanks, looks clear and appropriate for the Exceptions section. Stand by while I get a deeper review! |
| <a id="summary"> </a> | ||
| ## Summary | ||
|
|
||
| Even if stack traces may look intiminating at first, they are just a lot of diagnostic information helping you to find what caused the exception. As this information is often helpful in finding what caused the issue, you should typically not just ignore exceptions by adding a `System.err.println("An error occured");` or similar. Instead, either wrap the exception in another exception so that information about the original exception is preserved in a `Caused By` section or (if you actually want to continue executing after the exception occured) print the stack trace using the [`printStackTrace`](javadoc:Throwable.printStackTrace()) method. |
There was a problem hiding this comment.
Hi Dan,
There is a small typo here: intimidating instead of intiminating
| --- | ||
| id: lang.exceptions.stacktrace | ||
| title: Reading Stack Traces | ||
| slug: learn/exceptions/stacktrace |
There was a problem hiding this comment.
As this aims to be under exceptions portion, a slug_history element is needed.
| - Suppressed exceptions {suppressed} | ||
| - Reading bigger stack traces {bigger} | ||
| - Summary {summary} | ||
| description: "This article explains what stack traces are as well as how they can be read." |
There was a problem hiding this comment.
In my opinion, the description is hard to grasp. Maybe consider rephrasing that "as well" to "and"?
| <a id="intro"> </a> | ||
| ## What is a stack trace? | ||
|
|
||
| When an exception occurs in a Java program, a stack trace is often printed to the console. These stack traces often look scary, especially with complex frameworks but actually provide a lot of useful information for solving the issue causing the exeption. Specifically, stack traces show what exception occured as well as where exactly that happened and how the Java program got to that point. |
There was a problem hiding this comment.
In my opinion, using an emotion (look scary) in this technical context needs a justification. If I were to just find out about stack traces...why are they scary? (maybe the amount of content they have makes them scary)....
There was a problem hiding this comment.
Also, this section names induces to me the idea that I will find out what is a stacktrace and this definition is not clear enough "stack traces show what exception occured as well as where exactly that happened and how the Java program got to that point."
For me, a stack trace is a sequence of method calls that led to an exception being thrown in a Java program. A stack trace includes the names of the methods involved, along with the line numbers in the source code where the method calls occurred.
| <a id="simple"> </a> | ||
| ## A simple stack trace | ||
|
|
||
| Before coming to complex stack traces, we first investigate a stack trace originating from a very simple Java application. |
There was a problem hiding this comment.
As this is the first section containing right after the introduction and since complex stack traces were discussed before, I would suggest to omit the "Before coming to complex stack traces" and keep the actual introductory comment.
|
|
||
| First of all, Java tells us that we got an exception in a thread called `main`. As we haven't used anything related to starting other threads, this is the only application thread in this example. In applications involving multiple threads, the thread name can be a useful piece of diagnostic information. This part may be omitted or look different depending on what printed the stack trace. | ||
|
|
||
| After the thread name, the full class name of the exception is shown. As we have thrown an `IllegalStateException` in our example, this is `java.lang.IllegalStateException`. If a message is associated with the exception, that message is included in the stack trace as well. In our case, we passed the message `This is for demonstration.` to the `IllegalStateException` constructor resulting in that text being part of the stack trace. |
There was a problem hiding this comment.
If a message is associated with the exception, that message is included in the stack trace as well.
The above phrase implies an else case...so can there be a message in a stack trace not generated by an exception?
|
|
||
| After the thread name, the full class name of the exception is shown. As we have thrown an `IllegalStateException` in our example, this is `java.lang.IllegalStateException`. If a message is associated with the exception, that message is included in the stack trace as well. In our case, we passed the message `This is for demonstration.` to the `IllegalStateException` constructor resulting in that text being part of the stack trace. | ||
|
|
||
| The lines following start with the word `at` and provide detailed information on where the exception occured and what method calls lead to the program getting to that. The first such line is `at com.example.someapplication.StackTraceDemo.someMethod(StackTraceDemo.java:9)`. This tells us that the exception occured in a method called `someMethod` in the class `StackTraceDemo` located in the package `com.example.someapplication`. It also informs us that the exception was thrown in line 9 of the file `StackTraceDemo.java`. With many IDEs, you can even click on the `StackTraceDemo.java:9` and the IDE automatically opens the relevant file and navigates to the line in question. If we take a look at that line, we can see that it is `throw new IllegalStateException("This is for demonstration");` which matches the stack trace. Similarly, the next line is `at com.example.someapplication.StackTraceDemo.main(StackTraceDemo.java:5)`. This line tells us that where `someMethod` was called. This happened in the `main` method of our `StackTraceDemo` class. |
There was a problem hiding this comment.
The lines following start with the word at
Can you please tell me to what does start refer to?
| <a id="printing"> </a> | ||
| ## Printing stack traces | ||
|
|
||
| Sometimes, it is necessary to print the stack trace to the console or some other location when catching an exception without re-throwing it. For doing that, we can make use of the [`printStackTrace`](javadoc:Throwable.printStackTrace()) method. Calling that method prints the stack trace of a given exception to `System.err`. We can adapt our previous program to do catch the exception and print the stack trace by ourselves. |
There was a problem hiding this comment.
Sometimes, it is necessary to print the stack trace
As a reader, I would expect an example on when should I print the stack trace.
| <a id="cause"> </a> | ||
| ## The `Caused by` section | ||
|
|
||
| Sometimes, you might want to [throw an exception that was caused by a different exception](/learn/exceptions/throwing/#chained-exceptions). |
There was a problem hiding this comment.
I would love to have a justification on why (as a developer) would I want to do that 😄 . Maybe mention some best practice.
|
|
||
| Even if stack traces may look intiminating at first, they are just a lot of diagnostic information helping you to find what caused the exception. As this information is often helpful in finding what caused the issue, you should typically not just ignore exceptions by adding a `System.err.println("An error occured");` or similar. Instead, either wrap the exception in another exception so that information about the original exception is preserved in a `Caused By` section or (if you actually want to continue executing after the exception occured) print the stack trace using the [`printStackTrace`](javadoc:Throwable.printStackTrace()) method. | ||
|
|
||
| ```java |
There was a problem hiding this comment.
Just a thought: maybe you can consider refactoring this section to not end with a code section but with how looking at stack traces influence debugging.
|
After some internal discussion @danthe1st we are going to hold off on accepting this PR. Thank you for the effort and I'll let you know if we get to a point where we can re-work it for inclusion. |
Request issue
closes #53
Website section
Learn>Tutorials>Exceptions>Reading Stack TracesNotes for reviewers/specific decisions that may be worth reconsidering
lang.exceptionsand are in a group calledexceptions.05_exceptions. I did not include a00_exceptions.mdfile/index page for the exceptions page. Hence, it the exceptions article is not listed anywhere when rending the site using this repository (I can't copy the description of that series as that isn't under the UPL).More learningsection only seems to support YouTube links so that would need to be included in the summary or similar. (Alternatively, it would be possible to modify the_more_learningpartial)