Posts Tagged ‘Design’

OK, I’m putting this out there to see if I’ve missed anything that would be useful. This is the list of metadata that we’ll be storing about Modules in the PoshCode repository. It duplicates most of the information in the PowerShell Manifests, but it adds more of information that we feel is important for searching, sorting and organizing … and in the PoshCode Module manifests, wildcards are not allowed for any of the “export” values. The export information in the module is intended to represent the initial state of the module after import: listing all the cmdlets, functions, variables and aliases …

PoshCode Module Manifest Format:

GUID

The globally unique identifier for this module. Helps us tell modules apart

Name

The name of this module. Helps us find modules, and helps you guess what they’re for.

ModuleVersion

The version of this module. Together with the GUID, this is the unique key for the module. It should be incremented whenever you release it.

Description

A short description of the module. What it is, what it does, what it’s for.

ModuleType

Tells whether the module is a Script module or a Binary module (if they are both, then they are Binary).

Author

The person(s) who created this module. No organizations here, just people.

Company

A company (if there is one) that created this module or provides support for it.

Copyright

The copyright statement. You should always fill this out and assign copyright to the correct author, group or corporation.

License

The software license(s) that this module can be licensed under. It’s enough to use an acronym like “GPL v2” or “MIT” or “Ms-PL” ... but if you have a custom license you can specify a description of it or the full text of it. Multiple entries are allowed.

LicenseUri

The url(s) for a full copy of the license. If you’re using an open source license you can link to it’s page on opensource.org

Category

We’ll publish our official category list later, but the category is intended to be an assignment to a single category in a hierarchical tree.

Tags

A collection of user-assigned free-text keywords that help to categorize the module and serve as additional search terms.

Homepage

If the module has a home page on the internet, this is the URL. You can use the link to the PoshCode Docs page (which our cmdlets will generate for you) if you don’t have your own page.

Download

This is the link to download the module. If you’re hosting it on PoshCode, we will fill this in. If you’re hosting it elsewhere, this must be a download link. If it’s a commercial module that requires payment, you should leave this link empty unless you have a free trial download. Note: I’m still working on the commercial angle. Would it be helpful to include the price here? If we offered a way to sell your modules through PoshCode, would you use it?

RequiredAssemblies

Assembly names (or relative paths, if the assemblies are included in the module folder) for assemblies that must be loaded before the module will work. These should be the Assembly FullName, not a partial name.

RequiredModules

The names and versions (and GUIDs) of any modules that this module depends on.

PowerShellVersion

The version of Powershell required (2.0, for now).

FrameworkVersion

The version of the .Net Framework required. The framework version implies the CLR version, so we’ll just stick to this. I’m still toying with the idea of saying the list is 2.0, 3.0, 3.5, 3.5.1, and 4.0 … rather than allowing the normal version with the full four digits.

VersionChanges

This is either the list of changes in this version, or a complete list of the changes in previous versions.

Exported Cmdlets

The list of (binary) cmdlets exported by this module.

Exported Functions

The list of script functions exported by this module.

Exported Aliases

The list of aliases exported by this module.

Exported Variables

The list of variables exported by this module.

Deprecated things …

I’m leaning against having these items in the PoshCode manifest — they don’t seem to be helpful for finding or sorting or understanding a module.

• ModuleFile
• ModuleToProcess
• FormatsToProcess

• TypesToProcess

Comments Requested

I’m hoping for feedback about this list, what I might be missing, or if there’s anything in here I should leave out … let me hear it!

Awhile back I wrote a series of posts about WPF From PowerShell From PowerShell” which were about how you could load XAML in previous PowerShell 2 CTPs to create WPF user interfaces … a few people have mentioned loading XAML in PowerBoots, and a couple of people have posted other samples showing XAML even since I published the most recent release, so I figure it’s time to point out that you really can load that XAML into Boots, and get all the threading and other support.

Just for fun, I’m going to rehash an earlier post about updating windows to show how you can go about this using PowerBoots, and hopefully show that it’s a little easier (and a lot more async). Compare and contrast the code in this article with that one, just for fun.

This works with any version of PowerShell

Unlike the original article, most this code (except where explicitly mentioned) works on either PowerShell v2 with PowerBoots, or PowerShell 1.0 with PoshWPF, a snapin that is part of the PowerBoots module but is also released separately… Also, unlike those previous posts, this does not require you to be running PowerShell.exe with the -STA switch, since the New-BootsWindow cmdlet takes care of threading for us.

So we found a problem recently with a certain scripting language’s argument parsing:

Why can’t it properly parse -42 as an integer, when it can parse .5 as a double? Well, according to the development team of a certain Fortune 100 company, this behavior is by-design ... Apparently, “.” can be a number, but “-” can’t.

When you know you’ve got it all wrong, but you can’t be bothered to get it right, document it — make it look intentional, and most people won’t question you.

I’m sorry folks, but I’ve had it up to here with the “it’s by design” excuse. I don’t care who you are, and I don’t care who wrote the design spec — when something is as obviously wrong as this, you need to fix it, not just give us platitudes.

I had the same thing happen recently with a bug I filed about the way wildcard behavior impedes matching file-names with square brackets in them in PowerShell. They told me this was by design, and that I could use the -LiteralPath parameter. Well, if any of you have tried this, you already know what I’m going to say: it’s broken.

And yet, I was initially told it was supposed to be this way. Now, in this case, I happened to have the email address of the software architect, and they’ve reopened my bug after I sent him an email with lots of examples of how this bug defied the behavior that a user expects.

We software developers need to be very careful about saying “that’s by design” ... because it sometimes makes us sound stupid. When a user says “this is broken,” and your reply is “that’s by design,” what the user hears is “we broke it on purpose.” We should not be willing to excuse bad design.

Listen up: If you want to be a successful software developer, you need to learn this, and learn it well: the fact that it was DESIGNED WRONG is NOT AN EXCUSE for shipping broken software. Regardless of whether it’s your design, or someone else’s, even if it was designed this way by your manager’s boss. When you create software that doesn’t behave the way the user expects it to, you need to consider the possibility that you’re doing it wrong.

Imagine if architectural engineers were to behave in a similar manner … Suppose the original architect of the golden gate bridge had left a gap in the middle of the bridge, with a little ramp: you could drive up the bridge, but you couldn’t get across unless you were comfortable jumping your car across a four foot opening.

When you complained about it, the engineers would say: it’s by design — if you don’t like jumping your car (and yes, we know that jumping is bad for maintainability), there is a workaround: just wait for the ferry we put in last year. There are several boats, running continuously, so the wait is at maximum about 20 minutes, and it only takes a little longer to cross by boat than it would on the bridge.

That analogy is obviously not perfect, but the point is: just because someone decided it should be done a certain way doesn’t mean that’s the right thing to do — sometimes the design is just wrong. Perhaps the designer and architects overlooked something, or perhaps the circumstances have changed, but in any case, if the software doesn’t work the way people expect it to work, or requires different workarounds depending on the situation … you need to question the design.

All I’m asking is this: don’t turn your brain off: when someone complains about the way something works (or doesn’t work), think about what they’re asking, and if the complaint makes sense, don’t say “this misbehavior is by design” until you’ve reconsidered the design.

There are many desirable behaviors for Windows applications that are just much harder to do than they should be with the tools that Microsoft has provided in the .Net Framework. In WPF, many of these behaviors are even harder to create than in Windows Forms because the necessary hooks take a bit more work to write (thanks to the fact that there’s no window handles, so dropping down to “Native” code is harder. Luckily, WPF Attached Properties give us a whole new way to reuse these behaviors once they’re written.

I’ve started working on a few classes I’m calling NativeBehaviors, because they rely on intercepting the native Window Message processing, and I’ve put together a simple framework to let me write them, which I thought I would share. The first one I wrote is a SnapToBehavior, which implements a feature that people seem to be constantly re-implementing in apps. Basically, it makes a window snap to the screen edge when it gets close (and prevents them from being moved off-screen). I’ve also written a Global HotkeysBehavior which lets you register Hotkeys that work whenever your app is running (even if another app is active) so you can create a Hotkey to hide your app and show it, or whatever.

In the rest of this article I’ll show you how to achieve this in WPF using my base NativeBehavior class, and how to use it on a Window. Since some of you won’t really care how it works, let’s start with:

How to make your WPF Windows snap to screen edges in 3 easy steps:

Step 1. Add a reference to the Huddled.Wpf.Interop library.
Step 2. Add my Xml namespace to your root Window element
Step 3. Paste three lines from below….

I should point out the “SnapDistance” property of the SnapToBehavior is actually a WPF “Thickness” which lets you specify the distance from the screen edge as a single number to use on all sides, or as a separate number for each side: Left, Top, Right, Bottom. And that’s pretty much all there is to know.

How to implement a NativeBehavior.

The implementation of the SnapToBehavior is actually ridiculously simple, given the NativeBehavior framework. I simply created a SnapToBehavior class which derives from NativeBehavior, and implemented the single mandatory method:

When my new behavior is added to the Behaviors collection, my handler will be registered, and whenever the WM_WINDOWPOSCHANGING message arrives, it will be called. Now I defined a DependencyProperty for the SnapDistance, so that you could set that in XAML. It’s extremely simple, and VisualStudio has a built-in snippet for dependency properties, but here’s the code:

Once I have that, the last piece of the puzzle is to actually handle the window position changing message (think of it as an event, if you’re not used to Win32 message-based programming).

The basics of handling WM_WINDOWPOSCHANGING is that you get a structure passed in which has the proposed position of the Window, (including it’s z-index related to other apps) and you can basically tweak that however you like. Obviously there are lots of possibilities for this single message: always-on-bottom windows, undraggable windows, etc., but in our case we’re just concerned about how close we are to the edge.

We use the SystemParameters class to get the VirtualScreenLeft, VirtualScreenTop, and VirtualScreenWidth and VirtualScreenHeight which define the rectangle we’ll use for snapping. In the case of non-rectangular arrangements of multiple monitors this isn’t quite sufficient, but for our example anything more would be a distraction. Then we just check to see if the proposed position is within the “SnapDistance” of any of the edges, and if so, we change the position to be against the edge. That’s really all there is to it.

If you look at the code example below you’ll see I have to “Marshal” the WindowPosition structure in and out of an IntPtr which is passed in the WindowMessage … that’s the downside of intercepting window messages that the framework doesn’t already translate for us, but in this particular case, it’s actually fairly trivial.

Download it, or get the source code

If you’d like, you can download the current Huddled Interop for WPF library right now, or you can check out the source from CodePlex SVN or just download the most recent commit (You are only interested in the “Huddled” project which is in the “trunk”, not the “trunk-3.5”). The source is licensed freely under the BSD or GPL v2 (and a few other licenses, see the top of the source code files).

Either way you’ll get not just the SnapToBehavior but also the global HotkeysBehavior, and the Native Behaviors framework which I’ll write more about later, but for now, in case you want to try to use it, here’s an example using both the SnapTo and HotkeysBehavior (you can find this in the GlobalHotkeys demo project, which includes some sample code for handling hotkey conflicts). Enjoy.

So I’ve been asked to add a feature to one of the apps that I nominally took over when my former manager left … they want a management pane where certain authorized super users (to be decided later) can add data to the main lookup tables, and must be able to do clean up by deleting data which has been entered erroneously … including cleaning up any references to the now missing data.

I’m currently trying to figure out what database tables I need to be concerned with, and I just have to vent, because this system is the worst mess I’ve ever seen.

• There’s one database supporting five or more applications…
• There are 87 tables (with names like tblAQ_DcSs, tblAQ_SwNw, tblSFM, and tblSW_PWSOS, tblTestCaseTestLayout )
• There are three duplicate user tables: tblPeopleLookup, tblUser, and tblUser3 — tblUser2 is a view onto an external user database which is what is supposedly being used … and apparently, tblPeopleLookup is some sort of mapping from tblUser2 to tblUser3 … and tblUser1 is the original user table. I don’t know why these are all still here — I can only hope none of these others are still being used.
• There are 144 stored procedures (with names like sp_Fix, sp_Fix2, sp_Fix3, spLeftToTestMulti, spLeftToTestMulti2, spLeftToTestMulti3, sp_Whatever, and the awesome spTestCaseTestLayoutTestsUpdate, spTestCaseTestLayoutTestsSelect, etc.)

• There are no Foreign Keys. Yeah. None.

Technically, there are lots of foreign keys — it’s just that none of them are declared as such, so there’s no referential integrity (did I mention that there’s an access database floating around out there with linked tables and a hard-coded login which the end-users pass around to each other so they can insert data into some of the tables by hand because the original developers didn’t get around to writing this management app that I’ve been asked to write now?)

You can tell that some of the columns should be Foreign Keys, because obviously a column in a “tblReq_Tag” table named “Feature_ID” must be an external lookup of some sort … but there’s 86 other tables … and at least two of them have Primary Keys called “Feature_ID” ...

So, I’m spending a lot of time searching the source code and the 144 stored procedures … An astonishing number of these stored procedures involve cursors and multiple nested case statements. I just picked one at random which I thought sounded simple: spEnterGroupResults ... it’s about 150 lines of SQL, and it uses a single cursor variable “crsUnit” which it redefines three separate times onto three different queries which it iterates over. Each of these queries involves joins onto nested subqueries, and I count myself lucky because the tricky part is actually enclosed in a transaction, and at least this one isn’t doing all of that just to dynamically generate a further SQL query to execute.

So yeah, I’m literally looking through source code to try to understand the database design. The problem is that there are more than five different applications, each using slightly different technologies.

• One of them which has never been migrated from classic ASP ... with the business logic written entirely in Javascript, and the data handling performed entirely by sending huge XML files back and forth to a “do all” webservice.
• One of them was written in VB.NET in VS 2003, and has never been upgraded.

• The rest are in C# — with most in VS 2005, and at least one in VS 2008 and C# 3.0 — some are Asp.Net, some are rich client …

The tables I’m most concerned with right now (for this app) have some ahem ... impressive design decisions of their own. Of the 8 tables that I’m looking at directly (I think these are the only ones I need to modify as part of this app), five of them have multi-column primary keys that involve more than half the columns in the table, including columns which are, in fact, unconstrained foreign keys. And there are so far 5 foreign key looking columns which I haven’t been able to find the primary key column for …

Edit: Oh yeah, and half of these tables have columns like [Enabled] [char](1) NULL … That’s a boolean value folks, stored in the database as a y or a n … and it’s nullable even though a null (or any value other than y or n, really) will most likely blow up some code somewhere. And no, there’s no script constraint or trigger to ensure that this doesn’t happen (I checked). For extra fun, the other half of the tables use ‘bit’ columns for things like this — because they were written after I started working with this team (on a different project) and happened across one of these char columns during our one and only code review ever and wondered aloud why we needed to pretend it was still 1992. Why they just switched, without changing the others, I’ll never know…

I have only one thing to say about coverflow.

The LOOK of coverflow, and it’s complete lack of integration into the LOOK of … well, anything else in finder, frankly…. just reminds me of Monty Python’s credits: “completed in an entirely different style at great expense and at the last minute.”