WineHQ
WineHQ

2.6. A Few Notes on Style

This new scheme makes certain things more consistent but there is still room for improvement by using a common style of debug messages. Before I continue, let me note that the output format is the following:

yyy:xxx:fff message
where:
yyy = the class (fixme, err, warn, trace)
xxx = the channel (atom, win, font, etc)
fff = the function name

These fields are output automatically. All you have to provide is the message part.

So here are some ideas:

  • do not include the name of the function: it is included automatically

  • if you want to output the parameters of the function, do it as the first thing and include them in parentheses, like this:

    TRACE("(%d, %p, ...)\n", par1, par2, ...);

  • if you want to name a parameter, use = :

    TRACE("(fd=%d, file=%s): stub\n", fd, name);

  • for stubs, you should output a FIXME message. I suggest this style:

    FIXME("(%x, %d, ...): stub\n", par1, par2, ...);

  • try to output one line per message. That is, the format string should contain only one '\n' and it should always appear at the end of the string.

  • if the output string needs to be dynamically constructed, render it in memory before outputting it:

    char buffer[128] = "";
    
    if (flags & FLAG_A) strcat(buffer, "FLAG_A ");
    if (flags & FLAG_B) strcat(buffer, "FLAG_B ");
    if (flags & FLAG_C) strcat(buffer, "FLAG_C ");
    TRACE("flags = %s\n", buffer);
    Most of the time however, it is better to create a helper function that renders to a temporary buffer:
    static const char *dbgstr_flags(int flags)
    {
        char buffer[128] = "";
    
        if (flags & FLAG_A) strcat(buffer, "FLAG_A ");
        if (flags & FLAG_B) strcat(buffer, "FLAG_B ");
        if (flags & FLAG_C) strcat(buffer, "FLAG_C ");
        return wine_dbg_sprintf("flags = %s\n\n", buffer);
    }
    
    ...
    
    TRACE("flags = %s\n", dbgstr_flags(flags));