[Development] tracing to generate sequence diagrams (was Re: Proposal: Changing the default output of qDebug and friends)

[Shawn Rutledge]

On Wednesday, March 28, 2012 02:39:35 PM ext kai.koehne at nokia.com wrote:
> Hi there,
> 
> In Qt 4 qDebug, qWarning etc just printed whatever was passed in. In Qt 5
> we've been changing this (1) so that you can configure Qt to print
> additional information by setting the QT_MESSAGE_PATTERN environment
> variable. However, we didn't change the default so far - so without setting
> QT_MESSAGE_PATTERN we still just print the message. I just had a discussion
> (2) with Thiago Macieira and David Faure where we agreed that we'd like to
> still change this for Qt 5.0 ...
> 
> My personal motivation is that if e.g. the type would be always part of the
> message Qt Creator could use this information to colorize/filter output.
> Adding the app name / PID would identify the app in case of system logs,
> adding the function would give you a clue where on earth you added this one
> debug statement just printing "true" ;)

Since I'm working with mouse events lately, and event propagation is kindof 
confusing, I was thinking I'd like to have a qTrace() feature which would be 
rather like qDebug except that it would accept extra parameter(s) to define 
the "context" or "flow" that is being traced, and it could be separately 
turned on/off and separately redirected.  This is what I would do with it:

http://www.umlgraph.org/index.html

(the lower half about sequence diagrams)  In fact, a few years ago on a Qt-
based project I used specially-formatted comments in code to define sequence 
diagrams; it's just another "literate programming" technique, nice to be able 
to define the sequence diagram inline with the code the same way as you can 
define your documentation inline with code.  But you still have to think like 
a computer to make it work with comments, because the sequence does not come 
out of the execution order, you have to know what it will do in which order.  
Using qTrace would output something which depends on the actual runtime 
execution order, and that would vary depending on the use case, so you could 
generate a family of diagrams, one for each autotest as well as anything else 
of interest.

Maybe I could use some kind of existing debugging technique (like the same way 
that gdb does breakpoints, make some sort of auto-continuing breakpoint which 
just traces the fact that it has been hit).  But that would require a lot of 
setup to define just for one test what the breakpoints should be.  Or has that 
problem been solved already?  If there was a tool for scripting which 
functions need the trace breakpoints in order to document which "flow", they 
could be applied without adding anything to the source code.  But depending on 
the implementation of such a thing, it might be limited to tracing function 
enter/exit, whereas qTrace could go anywhere.

Event propagation is a "flow" which is of long-term interest, and the 
correctness of the flow is important both for testing and for documentation.  
A lot of bugs could be found by comparing before-and-after diagrams when 
changes are made.

Longer-term, Creator could generate selected types of diagrams whenever you 
use the debugger.  It would give you a more zoomed-out view of execution than 
what you can get by just setting breakpoints and looking at stack traces 
(which must be repeated because unless I took notes, I probably forgot what I 
learned last time).  

Quite often in preference to using breakpoints, I add a lot of qDebugs for 
tracing, but it's bad etiquette to leave them in place.  If there were an 
acceptable way of doing tracing, they could be left in the code, but the 
compiler would leave them out of non-debug builds.  (It's of course important 
for performance that they disappear completely from release builds.  That 
basically means qTrace should be a macro so it can be #defined to do nothing.)  
Creator's editor could optionally hide or collapse qTrace lines too, for 
anyone who minds the clutter.

-- 
MVH, Shawn Rutledge ❖ "ecloud" on IRC