2.7. 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));