[TOS] Start on "Designing the Code"

[Matthew Jadud]

Hi all,

http://teachingopensource.org/index.php/Practical_OSS_Exploration_-_Designing_the_Code

I started my work on "Designing the Code." I'm going to explore design
"in the small" and "in the large". In the case of the former, I'm
recommending students follow the "design recipe" as put forward in How
to Design Programs. It recommends a data-driven approach to
understanding what you are writing at the function/method/procedure
level, and this kind of structure is something I find many students
lack when they sit down to try and write code. I'll close by pulling
Javascript examples from open source projects (eg. Firefox) that don't
come close to following any kind of methodology "in the small," and as
a result the novice is constantly left trying to figure out what is
going on, simply because the developers didn't give us any clues. A
function like "openWindow" in nsBrowserContentHandler.js (the 192src
tarball) is a good example:

// Flag used to indicate that the arguments to openWindow can be
passed directly.
const NO_EXTERNAL_URIS = 1;

function openWindow(parent, url, target, features, args, noExternalArgs) {

// ... cut a bunch of code ...
  return wwatch.openWindow(parent, url, target, features, argArray);
}

We have no idea what the types are of the four parameters being passed
(not even Petzold's Hungarian notation to help us), and the only
comment I see tells me that there is some kind of magic constant that
controls how parameters are passed to this function. Beyond that, I
hope there are higher powers to help developers who are looking at
this code for the first time. (I'd welcome other/better examples of
this kind of obfuscated code in open projects, but I don't want to get
bogged down. A better example, though, would be nice.)

"In the large" I'll explore larger issues of design, communication,
and collaboration.

It's draft text, but it gives you a flavor. Comments welcome.

Cheers,
Matt