Writing tips on Samebug

Exceptions cause so much hassle in developer’s life. If you have some experience with the JVM, probably you are already familiar with some exceptions, and you have an idea how start fixing it. If you see a `NoClassDefFoundError`, you know that you are missing a dependency. If you see a `NoSuchMethodError`, you know that the library in the execution environment is a different version from what you compiled against.

However, it takes time to learn how to handle these problems. The first time a developer sees such a problem will cause her serious headache to find out what’s going on. On the other hand, even experienced developers will see new exceptions time to time when trying out a new tools. The problem with exceptions during development is that they make you lose focus. Instead of developing what you originally planned now you are trying to understand this unexpected situation, browsing the Internet, reading forums not even related to your problem, and suddenly your development has a research overhead.

Tips for the rescue

Our goal at Samebug is to reduce this overhead with Tips. Tips are short solutions to an exception. They are limited in size (256 characters) because we want to present them in a whole as soon as possible when you have problems with an exception. Our best approach at the moment is the IntelliJ plugin, which displays the tip right next to the stack trace in your console, but you will see them on the Samebug website, too. The goal of tips is to minimize the time you have to spend with these exceptions and get back to your workflow as soon as possible.

In the left column of the console, the Samebug plugin will display the bug icon when there is a tip for this stack trace.

How you write tips

If you have a crash on Samebug (either in the plugin or on the web), you will find a ‘Write a tip’ button. Our general guidelines about tips:

• The message must be longer than 5 characters and cannot be longer than 256 characters. We know that not every problem can be solved with a sentence, but the greatest value of tips is that the reader can glance over them and decide if it helps or not.
• Use markdown where necessary. Highlight code fragments and urls to make your tip more readable, but probably you want to say something too complex if you want to use lists or tables.
• Be straightforward, definite and short. You don’t have to be shy in your tip, just avoid the words ‘probably’, ‘maybe’, ‘in my case’, etc. Don’t be afraid that your tip will be displayed to people whose problem is different, that’s the job of the Samebug engine (which means that it still happens, but it’s our fault, not yours).
• Do not try to explain the details of the situation. Don’t try to generalize your tip by considering other cases where this tip could help. Focus on the solution that fixed your own crash. Keep in mind what would’ve helped you the most when you got this exception for the first time.
• Do not cover multiple situations. If you have multiple solutions for an exception, write them as separate tips.

When you write your tip, you can add a link as ‘source’. If the tip you write is an extract of a content from an other site on the Internet, please always give credit to the original authors by linking the specific answer:

• on Stack Overflow, click the ‘share’ label under the answer and copy&paste that link,
• on GitHub, click on the time label on the top of the comment and copy&paste that link,
• on Google Groups, click the dropdown arrow on the top right of a comment and copy&paste the direct link.

What happens with your tip

After you write a tip, the Samebug engine will use it as a solution for problems similar to yours. Let’s not get into the details and say that Samebug will display your tip to users when the root cause of your stack traces matches. If they are happy with it, they will mark it as helpful, which boosts your profile. If they aren’t happy with it, they can mark it ‘not helpful’, and Samebug will learn not to display it for those problems (well, soon or later).

Under your profile on https://samebug.io, you find a list of your tips. You can edit them here, check how many people have seen them and marks have they collected. If you open the details, you will also find a list of the exact stack traces where your tips are considered helpful (by you or by other users).