9.8. 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, ...);

• 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. (there are many reasons for this requirement, one of them is that each debug macro adds things to the beginning of the line)

• if you want to name a value, use = and NOT :. That is, instead of saying:

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

  say:

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

  use : to separate categories.

• try to avoid the style:

  FIXME(xxx, "(fd=%d, file=%s)\n", fd, name);

  instead use:

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

  The reason is that if you want to grep for things, you would search for FIXME but in the first case there is no additional information available, where in the second one, there is (e.g. the word stub)

• if you output a string s that might contain control characters, or if s may be NULL, use debugstr_a (for ASCII strings, or debugstr_w for Unicode strings) to convert s to a C string, like this:

  HANDLE32 WINAPI YourFunc(LPCSTR s) { FIXME("(%s): stub\n", debugstr_a(s)); }

• if you want to output a resource identifier, use debugres to convert it to a string first, like this:

  HANDLE32 WINAPI YourFunc(LPCSTR res) { FIXME("(res=%s): stub\n", debugres(s)); }

  if the resource identifier is a SEGPTR, use PTR_SEG_TO_LIN to get a liner pointer first:

  HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type ) { [...] TRACE(resource, "module=%04x name=%s type=%s\n", hModule, debugres(PTR_SEG_TO_LIN(name)), debugres(PTR_SEG_TO_LIN(type)) ); [...] }

• for messages intended for the user (specifically those that report errors in the wine config file), use the MSG macro. Use it like a printf:

  MSG( "Definition of drive %d is incorrect!\n", drive );

  However, note that there are very few valid uses of this macro. Most messages are debugging messages, so chances are you will not need to use this macro. Grep the source to get an idea where it is appropriate to use it.

• For structure dumps, use the DUMP macro. Use it like a printf, just like the MSG macro. Similarly, there are only a few valid uses of this macro. Grep the source to see when to use it.