Error Messages

[Magtheridon96]

Error and Warning Messages in Public Libraries

Introduction

In this mini-tutorial, I will be discussing proper Error and Warning messages.
This is something a lot of people get wrong and I'm sick and tired of it, so I'll
be showing you how to make proper error/warning messages that make sense.​

Problem

In many of the libraries I find crawling this website, I see very ambiguous
error messages that would make no sense in game or be any helpful.
Consider the following in-game screenshot:

Screenshot

Do those error messages seem helpful at all? Does the first one mention a spell?
Do any of them mention where the errors/warnings are popping up? In a large
map, how would I know where to look in my code when I'm getting meaningless
errors popping up and filling my screen? How would I know if what I'm getting is
an error or a warning? These debug messages are creating problems, not solving
them.​

Solution

My solution to this problem is to standardize error/warning messages. Personally,
I use the following format:

[Library] [Function] Type: Description​

Key:

• Library: This is the name of the Library or the package. In vJASS, you would
  use the name of the library in the header or the scope name. In JASS, you would
  use the name of the resource or the trigger that it's in. (Either way, this should
  not cause ambiguity problems because in vJASS, it is commonplace, and even
  expected of a user to use the library name as the trigger name.)
• Function: This is the name of the function or the static struct method in which
  the error is. In the case where you have a method, you would also display the
  instance like this: [(Instance).Method] where "Instance" is the integer that
  represents the instance of the struct and Method represents the method name.
• Type: This is either "Error" or "Warning".
• Description: This is where you briefly explain what's going on.

Following the above convention, this is what debugging would look like:

Screenshot

Conclusion

This kind of formatting in error messages allows us to find the origin of
bugs in our code. It allows us to debug maps faster and spot bugs easier.
It's also important to make the distinction between a Warning and an Error.
When it's an error, something went wrong and it should be looked at, but
when it's a warning, something was done incorrectly but it was handled
accordingly and it should be looked at. Another nice thing to do is to color
them as I did in the screenshot.

Stay in school, don't do drugs and all that.​

~Magtheridon96

 

[PurgeandFire]

Awesome format. I love it. I'll try to use that format in my libraries from now on.

Approved.

 

[WaterKnight]

You can omit the library, just print the full path of the function. Also I would reduce the indication of the warning/error nature to the color or an abbreviation. You often need space for parameters. Or append the line number of an exported logfile for further information to look up. In any way, how about using a debug library?

 

[Daffa]

Can this be used on GUI?

Anyway, seems nice have a +Rep

 

[Magtheridon96]

You can omit the library, just print the full path of the function. Also I would reduce the indication of the warning/error nature to the color or an abbreviation. You often need space for parameters. Or append the line number of an exported logfile for further information to look up. In any way, how about using a debug library?

Well, yeah, you can omit the library. You're right about the reduction of the Error/Warning indicator. I guess the color would be enough

As for the debug library suggestion, yes, that's perfectly plausible. We can write one and combine it with a Logger like the one Almia wrote. It would put whatever needs to be said in the correct format.
Not sure who has the will-power to do that though . If someone can make a Debug Utility library with proper printError and printWarning functions that takes a source function name and a message, that would be awesome. What would be cooler is if the library ALSO logged the messages to a file.

I'll update this when I can.

 

[mckill2009]

I must admit, this is helpful, but can I do like this?
[Library_FunctionName] ERROR: message
and pls do tell what display type to use, for all or 1 player?

this can be used in GUI as well, just go to 'Game' trigger and display like this:
[Trigger Name] ERROR: message

 

[WaterKnight]

If you use a library, this one can be configured because maybe you want to have a different output type or filter out unimportant messages for the moment. You cannot just log everything externally either as this is a very slow action.

 

[Magtheridon96]

Really, as long as the messages are being meaningful about their source, they're fine.

 

[edo494]

I dont know if this helps but did you know that putting thistype to string will make it rewriten to the struct name?

struct MyStruct
    static method something takes nothing returns nothing
        call BJDebugMsg("struct thistype, method something: error calling")
    endmethod
endstruct

will result in:
struct MyStruct, method something: error calling

 

[Magtheridon96]

Oh God.

This is either a clever feature or a sign of badly written software.