Re: [Jack-Devel] major change in jack1 MIDI handling

On Wednesday 16 October 2013 10:25:58 Devin Anderson wrote:
> A few years ago, I would have had more to say (and did, at times,
> IIRC).  I'm not as familiar with the JACK 2 codebase as I used to be.
> 
> And you're right - it's not fair for me to express my dislike of the
> JACK 2 architecture, design, etc. and not give some specifics.
> 
> One problem I remember trying to wrap my head around was the Open
> functions in the JACK 2 driver system.  Let's take a brief look at
> those now.
> 
> 1.) The JackDriverInterface class has three pure virtual Open()
> functions.  IIRC, there isn't one driver I've seen that implements all
> three of these functions.  That's confusing.
> 
> 2.) Then there's the JackDriver class that extends the
> JackDriverInterface class.  The class is meant to be a base class, but
> it implements all three of the virtual functions.  These
> implementations are meant to be called by subclasses that override the
> JackDriver virtual functions, which is an ugly anti-pattern.  If
> JackDriver's Open functions are called without the overriding wrapper
> function, then hilarity may ensue when the underlying JackDriver part
> of the class thinks the driver has been successfully opened.

Yes, it takes a bit to read up on the current driver infrastructure and 
understanding the exact semantics behind the calls. Three things I found 
missing were: comments, comments and comments. That would have saved me a lot 
of time.

I know there are probably a lot of people here who still follow and defend the 
paradigm "don't read or write comments, the code must say everything, 
otherwise it's bad code". That was fine in the 70s and 80s, but nowadays 
that's not appropriate anymore due to rising complexities, constantly changing 
developer teams, sharper time constraints and so on. My opinion is that every 
struct/class head and every function/method should have API comments. But as a 
minimum this should IMO at least apply to all fundamental base classes.

If you read foreign code (with a certain amount of minimum complexity) and i.e 
just need to understand the semantic of only one single function/method, you 
often need to invest half an hour or even hours to understand the semantic 
behind that single function/method precisely enough to perform your actual 
task (due to the need of also learning the semantics of functions called 
inside the function of interest), which would have been probably just seconds 
or minutes if that function/method was sufficiently commented.

And since most code parts are much more often read by many people than 
actually changed, writing such comments is thus a little overhead for 
individual developers which pays off quickly in the team's overall time 
savings. Especially in projects where runtime efficiency is a strong 
requirement, since clean and intuitive topologies are easily sacrificed for 
efficiency goals.

CU
Christian

1382371291.15115_0.ltw:2, <201310211807.07794.schoenebeck at crudebyte dot com>