Wednesday, 17 June 2009

CCD Red Degree Retrospective

Well I’ve been wearing the Orange bracelet for a while but I haven’t been thinking about it too much. Before I get back into the Clean Code Developer series of posts here is a quick recap of what you should be doing to consider the Red level “mastered”:

1) You must Stay DRY. Ruthlessly eliminate duplication. Look for implicit concepts in your code and make them explicit. Extract, encapsulate and pretty please, no clipboard inheritance. Try to remember that the best programmers delete code.

2) You should Reflect Daily. And not by calling Object.GetType(). Actively look at what you are doing. Don’t just think it, write it down. Re-read it. Engage your brain in actively reinforcing the things you do right and altering your behaviour to avoid those things you don’t do right. If you do this every day you can’t help but become a better programmer.

3) You adhere to The Boy Scout Rule. For such a simple idea this has very powerful consequences. You can’t help but check in code and if each check-in makes your code easier to work with then that’s a recipe for success. Good little boy scouts can DRY up their code, they can analyse issues with Root Cause Analysis, they can ensure that everything required for a build is in Source Control and they can Apply Simple Refactorings. Remember that the day you stop improving it is the day your code is starting to rot.

4) Put as much as is reasonable in Source Control. It doesn’t matter which one. It doesn’t matter if you don’t think you need one yet. You will need one. They are easy to use and there are good free ones available. There is no excuse for not using a Version Control System. In this era of Distributed Version Control Systems you don’t even need a server. Just do it.

5) Apply Root Cause Analysis. Look beyond the symptoms and see the problem. Ask why. And then ask why again. Keep going until you get to real issue and then fix it so it never shows up again. Examine each bug as if it were a process problem (trust me it probably is) and adjust your process accordingly.

6) Know when to optimize. Almost never comes to mind. That doesn’t make it okay to right slow code, it just means that you should focus readability first. After all, if it’s slow and readable then someone else has a chance of being able to speed it up. If it’s fast and incomprehensible then no-one will ever tough it again. Factor out the part of the code you want to optimize so that different implementations can be slotted in. Never optimize without measurements to back up your decision and to verify your improvements.

7) Apply Simple Refactorings. You’d be surprised how much more readable software can become just by using Rename and Extract Method. You don’t need powerful tools to do this (although any version of Visual Studio will do both out of the box). Don’t be scared about having lots and lots of little methods. If we are (re-)naming them appropriately then our toolset provides a number of navigational aids to help us move around our code.

8) Keep It Simple Stupid. Prefer the simplest solution to any problem. Be aware when you are adding complexity and understand the reasons why. Try to remember the business value in what you are doing and ask if the client is willing to pay for the extra “scalability”, “flexibility” or “excuse to explore cool new thing X”.

8 simple steps but they are a good start down a long road. If you’re still with me then prepare to take off the Red band, wash your wrist and put on the Orange band.

Monday, 1 June 2009

we have no class (a personal journey of not learning OO)

Disclaimer – this is a commentary about the state of the industry not about my specific place of employment. If it were, I’d have quit and found another job already. I haven’t, therefore it isn’t. QED.

Disclaimer 2 – it got pretty long but I’ve been typing it on and off for a week and I’m not sure much more I can edit it. I hope it gets you thinking.

I feel as if the OO train left and very few people were on it. There I said it. Don’t feel bad if you missed it, I’m pretty sure that I’m not on it either. What the heck am I talking about? Let me explain.

In the beginning

Way back in the dark ages I learned to program (20 years ago now that I stop to think about it). I did this with an Amstrad CPC 6128. It had a built in 3” (not 3.5) floppy drive and I had a hundred programs on disk but every month something magical happened. A magazine would arrive (Amstrad Action) containing 3 or 4 pages of type-ins. These consisted of programs written in Amstrad BASIC which you would read from the magazine and type in by hand.

I was hooked instantly. I’d found a way of controlling my computer and it let me be creative and feel powerful all at the same time. I had no idea what I was doing of course. I was just a fleshy copy-paste mechanism, a form of chinese room.

Skip forward a few years. By now I’ve learned BASIC enough that I can cobble together some rudimentary programs of my own. The trick is to write down what you want to do and figure out the program flow. Then you carve that flow up into chunks and implement the chunks into different areas of memory.

You did this with line numbers. By default line numbers started at 10 and went up by 10 for every new line but you could restart the code at any line number. So you’d implement the drawing routine at 300 and the movement logic and 1000 and before long you had some kind of snake clone. It’s funny, even though these numbers were arbitrary I’d still occasionally be working on a section of program in the early part of the line numbers and accidentally overwrite a later part.

My primary units of program control were if statements, for loops and the dreaded goto. My primary units of data were primitive integer types, strings and arrays (of integers or strings).

The school daze

Fast forward a few more years. Now I’m in high-school and they’re teaching me Pascal. This language is great. There are no line numbers and you refer to functions and procedures by name. Each function can have sub-functions and functions from the outside can’t see those so you can define little areas of your program and focus on just those bits without ever running out of line numbers. If you get a really big program you can define units (but I never really do). 

I almost never use gotos any more but I use select-case statements and call functions a lot. To the for-loop I added a do-while and a repeat-until and of course if was still around. There’s pointers but that stuff is hard. In the data space we got the record which was amazing. Now I could start creating abstractions like person, customer and salesrecord. At least in class, my own programs lacked such sophistication. The most complex program I wrote in this era, a simulation of the classic board-game battleship, used 2 10x10 arrays so I saw no need.

Wander forward in time again. Not too far as I’m gaining momentum now. About half way through high-school. They’re trying to teach me logo (is that not a step down from Pascal?) but I bought a C++ compiler and snuck it into class. Here we can create classes which is this weird organizational thingy where we have a record with some functions on it (to save it to disk or print it on the screen or calculate age or whatever you needed). There’s also these things called objects which are related to classes somehow but I’m not entirely sure how. Apparently global variables are bad so you put them in a class which limit’s their scope (Pascal was big on scope so I know that word). There’s also this thing called inheritance where you can re-use code without copying and pasting but as everything is a function you can get a lot of re-use from having a large mass of parameters (or declaring class variables).

I guess you can tell that OO was completely lost on me. Polymorphism, Inheritance and Encapsulation are really big words that were explained to me in very academic language from very dry books and their meaning and it’s potential impact on me at this stage in my education are completely lost. Effectively I’m writing Pascal code using the C++ language.

Hire education

So I graduate high-school and move to university. Here they teach us assembly (using the IJVM) and functional programming (in gofer of all languages). It was a weird course. There is some C (which I figured was like C++ only far less confusing) and then we were introduced to Java.

This was a language in which everything is an object (or class, I hadn’t yet figured out the difference). If you wanted to write stuff to the screen you might call upon the services of screen object or if you wanted to read from a file then you’d use a file object. 

Lecturers spoke about encapsulation whilst showing a slide of a person object with a private dob field and a public getAge method. They showed us Inheritance hierarchies containing Shape, Circle and Square and how we could add a draw method to each and then draw a list of “shapes” without knowing which we were dealing with. In short very, very simple examples.

Next we were introduced to the UML Class diagrams. To me this notation (which is meant to help people understand object collaborations) just reinforced my views that the whole class thing was an organizational unit. After all what looks easier in a diagram? One box with one label that says “SendNewsletter” or 5 boxes that collaborate (whilst remaining decoupled) to send a branded, personalized monthly newsletter to some subset of users in a database.

In my experience UML makes it too easy for the inexperienced user to ignore complexity and give a complex issue a very shallow treatment. Every box becomes a Facade for a system you don’t bother to draw (and hence is never implemented).

I was in tertiary institutions for a total of 10 years (2 universities and 1 TAFE) and I managed to graduate without understanding Objects in the slightest. The few people that I am still in contact with from those days seem to be in pretty much the same boat. In point of fact, if I look around at the industry at large I don’t see a lot of people engaged in OO Design at all.

The Real World (TM)

Since leaving my structured studies behind and tackling more real world problems I have become more and more aware of the lack of OO knowledge in myself and those around me.

Whenever I’m confronted with an existing scenario and new complexity is introduced I open my tool-box and find find my trusty if-else-statement or switch-statement. After a while this makes my methods disappear off of the bottom of the screen and so I tend to use the handy extract-method refactoring which is built into Visual Studio to break it up a bit.

There are a few people that I’ve worked with (most I’d guess) who think that this is going a bit too far. After all, how are they supposed to figure out what is going on when I keep breaking bits of logic out on their own. Now they have to skip about the class looking at each of the methods in turn and use their highly-prized UML skills to construct a sequence diagram. Or they would if anyone cared about sequence diagrams. More likely they’ll invent their own diagramming technique for program flow and then use that which makes it impossible for them to effectively communicate their findings to anyone else.

People will lose the plot even more if you start adding in collaborating objects into the mix. Now they have to check in different files for what is going on and their home-spun diagrams have stopped making sense even to themselves. They say they’d prefer simplicity and maintainability and yet they refuse to acknowledge the benefits of the SOLID design principles. Oh that’s just for complex stuff, they’ll say. We just get data on and off of forms with some business rules.

I have some news for you. That IS the level of complexity of most systems. Most systems boil down to business rules, data entry and reporting. Most of the other stuff you do is probably to support one of those 3 things.

So why don’t we leverage Object Oriented design and thought processes? I think that Kent Beck and Ward Cunningham summarized what I feel the issue is quite nicely in their paper entitled “A Laboratory For Teaching Object-Oriented Thinking”:

The most difficult problem in teaching object- oriented programming is getting the learner to give up the global knowledge of control that is possible with procedural programs, and rely on the local knowledge of objects to accomplish their tasks.

Kent Beck, Apple Computer, Inc.
Ward Cunningham, Wyatt Software Services, Inc.

From the OOPSLA'89 Conference Proceedings 
October 1-6, 1989, New Orleans, Louisiana 
And the special issue of SIGPLAN Notices 
Volume 24, Number 10, October 1989

The very reason that OO became a dominant paradigm in the first place is because the programmers of the day were unable to keep track of the state of their entire application as those applications got bigger and bigger. To counter this effect they invented a technique for breaking the program into smaller chunks that could each act as a discrete unit and could delegate tasks out to or request required information from other chunks as required. This meant that the programmer no longer needed to know the state of the entire program to make changes. Instead we can work within the confines of a single class and assume that our collaborating classes know their job.

Very few of us seem to have mastered this (and I count myself as one who hasn’t). You can see that when people start writing down call stacks and setting breakpoints in their code. It is fundamental to the way a programmers mind typically works that we have to have all of the information. We cannot let go at the borders of a single object but we have been told that we must. So the solution is to cram as much into a class as we can. After all, a class that does 27 things is more reusable than one which does 2 or 3 right? And I can’t just add new classes to the system, who will update the UML diagram?

It’s interesting to note that some DO seem to get it. Many frameworks and libraries get quite clever and use OO techniques under the covers. These same libraries have a habit of throwing a darned Facade in the way making the end user capable of using them without understanding a single thing about how they work. I guess the smart guys got sick of the rest of us harping on about what we need to do to use their stuff.

Some frameworks get really bold and require us to create our own classes. The usually proscribe 2 or 3 types of class that are necessary (i.e. View, Presenter and Entity) and so we go about creating one of those whenever we really have to. We make those classes work really hard though don’t we? They end up with a lot of variables and methods. In fact they end up like little Pascal programs all on their own.

Is this a problem? I feel like Neo standing before Morpheus in The Matrix wondering whether to take the Red Pill or the Blue Pill. Either the industry is full of people making the same mistakes over and over or I’m fooling myself about our potential effectiveness.

I don’t have all the answers but I’m attacking this one the same way that I usually do. Reading voraciously and trying to absorb so much knowledge that hopefully some small portion will stick. I’m looking for good materials on learning (and teaching) good OO techniques so if you know of any, leave me a comment.

I believe that this isn’t an effective way of learning OO techniques though. They need to be applied to real world problems. Ones that have jagged edge cases.

I think that taking special care of the Single Responsibility Principle and aggressively refactoring code regularly will help. I also think that designing for testability (and in particular Test-First) are also great at making us aware of where the edges of our classes are.

What do you think? Do you do OO? Are those around you baffled by your preference for creating new classes over new methods? Do they see you producing very small units of logic and data and wonder how you keep track of the big picture? Do they ever create a new class to encapsulate an existing concept or do they just create mammoth utility classes with 500 static methods?

The OO train may still be at the station. Have you got your ticket?

Wednesday, 27 May 2009

Learne ye crafte

I had the dubious honour yesterday of reviewing some “interesting” code. If you’d been watching my twitter stream you’d have seen that WTFs per minute metric was pretty high. Now that I’ve had some time to calm down I wanted to share some of the things that I found unacceptable about this code.

Just in case the authors happen to stumble upon this post I want to make it clear that my intention isn’t to shame you (in fact I’ve taken steps to alter the code making it less recognizable). I’m certain that I have violated each of these on several occasions and I hope that others can learn some anti-patterns from this post.

1. Your repository should be fully contained

In other words I should be able to check out the latest version from source control and build and run your app. If there are special environmental considerations (like files that should be in certain folders or assemblies in the GAC), then those should be well documented and then those items and the document should be placed into your source repository.

A good mechanism for ensuring that what’s in the repository always builds is to perform an automated continuous integration. That way as soon as something “breaks the build” you will know and someone will go in and fix it. Try to keep your CI machine as clean as you can. If you have to install a tool or plugin on the CI box to get the build to work then check the installer for that tool or plugin into the repository and  install it from there.

2. The worst form of comment is commented out code

Code can be in one of two states. Either it came from the repository or you wrote it in the current session. If it came from the repository then you can safely delete it knowing that you can always go and get it back out of your source control system later. If you just wrote it and you don’t want it in the production code base for some reason then DO NOT CHECK IT IN.

Checking in commented out code says to me that you don’t understand what the impact of not having that code there is (i.e. We might want that later if it turns out my change didn’t work). Take the time to actually understand what the code is doing and if some code is not necessary then delete it. Your brain can only hold so much stuff in it, don’t waste the room with irrelevant details.

The longer commented out code is left in the system the less relevant it becomes. This is because the rest of the code around it changes but those changes are not reflected in the commented out code. Frequently I’ve found commented out code that is only a few weeks old that calls methods whose signatures have changed or have been renamed, or deleted altogether, or moved to another class. I also come across code that accesses local variables that have been deleted. If you find commented out code in the repository just delete it. No-one else will have the courage, assuming that it’s someone else’s responsibility.

When you delete the code you might find that the surrounding code looks a little absurd. Here’s my favourite sample of the week:

public Letter ClientLetter_Get(string type)
{
Letter rv = null;
//rv = _client.Letters.Find(item => item.Type == type);
return rv;
}



You don’t have to look too closely to see that this method now returns null all the time. Without the commented code the method has become superfluous as well. We should delete it as well and who knows how far that would cascade down. As it turns out this method is used during binding to determine whether certain controls are visible or not. As the method will always return null, the controls are never rendered so they and all their event handlers can now be deleted. Hundred of useless lines of code, just gone. Here’s one more:



if (_engagement == null)
{
return "";
}
else
{
return "";//_engagement.PersonnelRole.Personnel.Rep;
}


Even with the comment still intact this looks a little ridiculous. How much of the rest of this method (not shown above) is made completely superfluous knowing that we’re going to return an empty string no matter what?




3. Code blocks that do nothing are worthless at best and putting a comment in them explaining their purpose doesn’t help



This is one I haven’t come across that often but is rife in the code I’m reviewing so it may be more of an issue out there than I thought. Here is the most absurd case:



byte[] array = new byte[file.ContentLength];
int size = file.InputStream.Read(array, 0, file.ContentLength);
if (size < file.ContentLength)
{
//err
}



Error handling via comments?! If you are going to go to the trouble of detecting an error condition then you had better be prepared to do something about it. If not, just delete the whole if statement and get on with it. There are some less obvious versions of this though. Here’s one



switch (e.CommandName)
{
case "LOAD_XL":
if (e.CommandArgument == "MainFile")
{
Display_File("MainFile");
}
else
{
Display_File("SecondaryFile");
}
break;
case "UPLOAD_XL":
break;
default:
break;



What is the point of having UPLOAD_XL in there? if you delete it then the default case will be executed anyway. Even that is superfluous as it’s blank so you can delete that too. That leaves you with a single case and in my books that’s an if statement. You could even clean up that existing if statement as well but that’s beyond the point here. Last one for this section:



if (personID == null)
{
//null personID
}



That comment really clears things up for me, thanks. There’s a bunch of else-if clauses which makes me suspect that this is an attempt to prevent duplication but that’s a different scary story.



4. Copy and Paste is not reuse, it’s abuse



I’ve ranted on this topic before so I won’t go into too much detail here. If you express the same concept/algorithm in 20 distinct places then you will never be able to change that concept/algorithm. It’s time expand on the null personID sample from above:



object personID = Session[SESSION_ENGAGEMENT_PERSONNELID];
int PersonnelId = -1;
if (personID == null)
{
//null personID
}
else if (personID.GetType() == typeof(string))
{
if (!string.IsNullOrEmpty((string)personID))
{
PersonnelId = int.Parse((string)personID);
}
}
else if (personID.GetType() == typeof(int))
{
PersonnelId = (int)personID;
}



This exact piece of code is repeated verbatim in 5 places in one file. At the very worst it could be extracted as a method and called from 5 places. An even better solution would be to wrap a property around it (why? Because then you could provide a setter as well and completely encapsulate the Session access).



Also on a side note, if you look at what is going on here it seems as if the implementer doesn’t know what type he/she should expect to find in the session variable either. That’s a bit sad as a quick find all references tells me that it is set in 3 places and each one sets it to a string. Had the developer wrapped a property setter around the code that updates the session variable they would have had more confidence about what to expect from the session.



5. The ternary operator in C# has a time and a place



Many people don’t like the ternary operator (?:) in C# stating that they find it makes code more difficult to read. I think under some circumstances it can enhance readability but it’s use has be carefully managed. For instance, I would definitely use it here:



if (_personnel == null)
{
return null;
}
else
{
return _personnel.Updated;
}


To get the more terse (but I don’t think less readable):



return _personnel == null ? null : _personnel.Updated;



But probably not here where I think your eyes (and brain) have to jump around too much to figure out what is going on:



value.ApplyFilter(
item =>
(
item.PersonnelRole.Personnel.Client.DeliveryManager == null ? false
: (item.PersonnelRole.Personnel.Client.DeliveryManager.Name == _currentUserComment)
)
||
(
item.PersonnelRole.Personnel.Client.Exec == null ? false
: (item.PersonnelRole.Personnel.Client.Exec.Name == _currentUserComment)
)
);



Anyone want to try and decipher that? Actually the original statement is a bit bigger and longer and I messed with the names to protect the innocent. Now it looks much tidier :)



To be continued…



I have much more to say about this code but I am getting kinda tired of looking at it at the moment and I’ve just been assigned a more urgent task. It’s possible that I’m just getting old and cranky (I turned 30 this week) but I’m pretty sure that most people out there would have been frightened by this code.

Sunday, 17 May 2009

BDD has me out of my Gourd with NGourd

As it seems that there is a buzz generating around NGourd on Twitter I figured I really should write a blog post about it. A few weeks ago there was an OzVAN session on Behaviour Driven Development and someone mentioned Cucumber. I found the power of being able to write specifications in plain text and yet execute and verify them using a command line tool very compelling. I promptly set about downloading IronRuby and trying to get Cucumber working against a C# project.

Despite many hours of messing about I couldn’t get that to work. After a few minutes of moping dejectedly about I remembered “Hey I’m a coder! If I want executable text specs then I’ll just make my own.” And so NGourd was born.

NGourd is an open source Behaviour Driven Design framework for .NET which is heavily inspired by Cucumber. I have to warn you that it’s in it’s infancy at this stage but here goes. This is a feature file:

Feature: Search

Scenario: Looking for my blog
Given I am at the home page
When I enter "wolfbyte" into the search box
And I click go
Then I should see a link to http://wolfbyte-net.blogspot.com

Scenario: Looking for weather
Given I am at the home page
When I enter "weather perth" into the search box
And I click go
Then I should see "Weather for Perth WA, Australia"


It should be pretty easy to read. The coolest thing about it is that it is actually executable! In fact this is a file called Search.feature which I just compiled into my pet NGourd test project, a set of Specs to test the behaviour of google.com. When this is run it uses the WatiN library to automate an IE window on my machine and carry out all of the steps in the above two stories. I hope that the sample text is clear enough that you wouldn’t be surprised watching it run.



By default the results are colour coded and dumped to the console. Here is the result of running the above:



NGourd.Google.Search.Output 



Thanks to @liammclennan you can now get an NUnit style XML report out of NGourd as well. Just specify “-o=outfile.xml”. It will also return a status code of –1 on a failed run so it should stop CC.NET (and possibly other Continuous Integration servers) with a broken build.



OK, so I told you it runs the script and offered some kind of proof (albeit in the form of an easily forged screenshot). How exactly does it know how to run the above script? The answer is Step Definitions Containers. A Step Definition Container is a class that defines which steps are available to a scenario and what to do when the step is encountered. Here is the step container which powers the above feature:



public class GoogleSteps : StepContainerBase
{
private IDictionary<string, string> Pages = new Dictionary<string, string>(StringComparer.InvariantCultureIgnoreCase)
{
{ "home", "http://www.google.com/" }
};

private static IE browser;

public override void BeforeAll()
{
browser = new IE();
}

public override void AfterAll()
{
if (browser != null)
{
browser.Close();
browser.Dispose();
}
}

[Step(@"at the (\w+) page")]
public void GotoPage(string pageName)
{
Assert.That(Pages.ContainsKey(pageName), "Missing Page");
browser.GoTo(Pages[pageName]);
}

[Step(@"enter ""(.*)"" into the search box")]
public void SearchFor(string query)
{
browser.TextField(t => t.Name == "q").Value = query;
}

[Step(@"Press Go"), Step(@"Click Go")]
public void PressGo()
{
browser.Button(b => b.Value == "Google Search").Click();
}

[Step(@"see a link to (.*)")]
public void EnsureLinkExists(string url)
{
Assert.That(
browser.Links.Any(l => l.Url.StartsWith(url)),
"No anchor tags that link to " + url);
}

[Step(@"see ""(.*)""")]
public void ShouldSee(string text)
{
Assert.That(
browser.Text.Contains(text),
"Looking for " + text + " but it wasn't here");
}
}



A Step Container inherits from StepContainerBase (actually it just needs to be annotated with a StepsAttribute but the base class does that for us and adds a few more goodies). Before all of the scenarios are run the BeforeAll method is run which creates a new WatiN IE window. After all of the scenarios are run the AfterAll method is run which disposes of the WatiN window.



The exciting part happens during the scenarios themselves. During each scenario the steps are run in the order provided. NGourd uses the StepAttribute annotations on public methods to select which method to run for each step. The annotations contain regular expressions which are used to identify the correct method to run and extract any parameters out of the original text as well. In this instance each step is only a couple of lines of code (usually one in fact).



If the step throws an exception it is considered to have failed (those Assert.That methods come from the StepContainerBase class and just hide the mechanics of throwing the exception). If one of the steps in a scenario fails then all of the steps after that are skipped and the scenario is marked as failed (which in turn marks the feature as failed). Here is the result if we change the PressGo method to throw an Exception:



NGourd.Google.Search.Failing



You can see the Then steps being skipped in each scenario after PressGo fails. A similar thing occurs if the step cannot be found. If we delete PressGo altogether then we get:



NGourd.Google.Search.NotFound



Again the last step in each scenario gets skipped but the test runner has been able to pick up the fact that the step couldn’t be found. This is great as it means you can start with a feature definition and then create the steps that you need. As you add scenarios to the system you can either add more steps to go with them or annotate existing steps with new regular expressions to make your testing language more flexible.



If you are interested in finding out more you might have to read the source code. If you want to try it out it is hosted on Google Code at http://ngourd.googlecode.com/



There is a quick start on the wiki as well: http://code.google.com/p/ngourd/wiki/QuickStart



Remember that this is not a stable release at this stage so I don’t recommend relying on it for production code. If you have any comments or questions feel free to leave them here, at the NGourd site or drop me an email directly.

Wednesday, 6 May 2009

Method hiding, stack trace manipulation and programmatic debuggery

Tonight I found myself using a few techniques that I’d never come across before. So I figured I’d document them before I forget what the heck was going on.

Some background first. I am working on a development tool not unlike NUnit. That is, there are two key components. The first is a library that contains some kind of API that you are supposed to call. In my case this is a fluent interface (or two). The second component is a command line utility that loads user code (in assemblies) and executes that code to achieve some effect.

Method Hiding

The first technique is very useful when you are writing Fluent APIs. It allows you to hide methods (or other members) from appearing in intellisense. Its easy enough, you apply the System.ComponentModel.EditorBrowsableAttribute to the method that you want to hide and initialize it with a System.ComponentModel.EditorBrowsableState of Never. Here’s a sample:

public class ClassWithSomeMethods
{
public void AVisibleMethod()
{
}

[EditorBrowsable(EditorBrowsableState.Never)]
public void AnInvisibleMethod()
{
}
}


Here is a snapshot of what the intellisense looks like:



HiddenMethod



The method AnInvisibleMethod is not present. You can still call it any time that you want it just will not show up in intellisense. This is particularly important for Fluent APIs because they tend to rely on intellisense to guide consumers towards the options that are available at any point during the Fluent chain.



There is still the 4 methods there that are inherited from object (Equals, GetHashCode, GetType, ToString). The bad news is that everything has those (well everything which inherits from object which is everything). The good news is that they are virtual so we can override them and then apply the EditorBrowsable attribute and they go away. If you need to do that a lot then you might consider putting all of that into an interface and then implementing that (you’d need to keep a track of your fluent object via an interface implementing that one otherwise the IDE gets clever on you). This is often done with a static accessor of some kind). Enough talk, more code. Here’s what it looks like:



[EditorBrowsable(EditorBrowsableState.Never)]
public interface IFluentApi
{
[EditorBrowsable(EditorBrowsableState.Never)]
string ToString();

[EditorBrowsable(EditorBrowsableState.Never)]
bool Equals(object other);

[EditorBrowsable(EditorBrowsableState.Never)]
int GetHashCode();

[EditorBrowsable(EditorBrowsableState.Never)]
Type GetType();
}

public interface IMyFluentApi : IFluentApi
{
IMyFluentApi ContextPreservingOperation();
TheNextFluentClass ContextChangingOperation();
}

public static class Fluently
{
public static IMyFluentApi Do
{
get
{
return new AFluentClass();
}
}
}

public class AFluentClass : IMyFluentApi
{
public IMyFluentApi ContextPreservingOperation()
{
// Do operation
return this;
}

public TheNextFluentClass ContextChangingOperation()
{
// Do operation
return new TheNextFluentClass(this);
}
}

public class TheNextFluentClass
{
private readonly AFluentClass source;

public TheNextFluentClass(AFluentClass source)
{
this.source = source;
}
}



FluentApi



One final word because this one drove me nuts. This technique does not work if you make a Project Reference instead of a normal Assembly reference. That means that if you start a new project in your current solution to test this out it won’t work. This apparently has to do with the way that the method meta-data is loaded.



Stack Trace Manipulation


I’m calling methods via reflection like this:



Method.Invoke(Target, parameters);


If you are interested, Method is a System.Reflection.MethodInfo. The problem is that if the method being called throws an exception then what happens is that Method.Invoke throws a TargetInvocationException with the original exception as it’s InnerException. Here is a quick sample:



class Program
{
static void Main(string[] args)
{
try
{
Execute();
}
catch (Exception ex)
{
Console.WriteLine(ex);
}
}

public static void Execute()
{
var target = new Foo();
var parameters = new object[0];

var type = target.GetType(); ;
var method = type.GetMethod("Bar");

method.Invoke(new Foo(), new object[] { });
}
}

public class Foo
{
public void Bar()
{
throw new Exception("Actual Issue");
}
}



When you run this you get:




System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.Exception: Actual Issue

   at ConsoleApplication1.Foo.Bar() in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 38


   --- End of inner exception stack trace ---


   at System.RuntimeMethodHandle._InvokeMethodFast(Object target, Object[] arguments, SignatureStruct& sig, MethodAttributes methodAttributes, RuntimeTypeHandle typeOwner)


   at System.RuntimeMethodHandle.InvokeMethodFast(Object target, Object[] arguments, Signature sig, MethodAttributes methodAttributes, RuntimeTypeHandle typeOwner)


   at System.Reflection.RuntimeMethodInfo.Invoke(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture, Boolean skipVisibilityChecks)


   at System.Reflection.RuntimeMethodInfo.Invoke(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)


   at System.Reflection.MethodBase.Invoke(Object obj, Object[] parameters)


   at ConsoleApplication1.Program.Execute() in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 30


   at ConsoleApplication1.Program.Main(String[] args) in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 14




Scary huh. The first line tells you that the method you called threw an exception. We knew that. After that is the two lines we actually want. Then there is a marker and then 6 lines of crap (actually there is 4 lines of crap and then 2 lines we could possibly use but we’ll get to that).



We could catch the TargetInvocationException where it occurs and throw its InnerException like this:



try
{
method.Invoke(new Foo(), new object[] { });
}
catch (TargetInvocationException tiex)
{
throw tiex.InnerException;
}



The result is possibly not what we wanted




System.Exception: Actual Issue

   at ConsoleApplication1.Program.Execute() in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 37


   at ConsoleApplication1.Program.Main(String[] args) in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 15




We’ve kept those last two lines (the ones going in) but lost the most important ones (the ones at the site of the exception). This happens because the throw statement reorganizes the stack trace. That means that if we try to do anything to manipulate the stack trace then when we hit the throw statement it will all be lost.



If you’ve ever done any remoting work then you’ve probably come across the situation where a call to a remote component that throws an exception has it’s stack trace persisted across the remoting boundary. How the heck does it do that?



When an exception propagates to a remoting boundary it is “prepped” for crossing. This involves taking the current stack trace info and appending it to an internal field called _remoteStackTraceString. When the exception gets to the other side of the boundary it is essentially rethrown and then your code can treat it however it likes.



In the course of handling that exception you might access the StackTrace property. It never occurred to me that this property was calculated. It actually concatenates the remote stack trace string with the local stack trace string. That means that if we want to be sneaky we can manipulate where it appears an exception comes from and retain all of the stack information from the point of manipulation back to the site where the exception is handled. There doesn’t appear to be any way to set _remoteStackTraceString from outside of the Exception class so we’ll have to use some reflection-fu. Lets see how that works:



public static void Execute()
{
var target = new Foo();
var parameters = new object[0];

var type = target.GetType(); ;
var method = type.GetMethod("Bar");

try
{
method.Invoke(new Foo(), new object[] { });
}
catch (TargetInvocationException tiex)
{
throw AdjustedRealException(tiex);
}
}

private static Exception AdjustedRealException(TargetInvocationException tiex)
{
var remoteStackTraceString = typeof(Exception)
.GetField("_remoteStackTraceString",
BindingFlags.Instance | BindingFlags.NonPublic);

remoteStackTraceString.SetValue(
tiex.InnerException,
tiex.InnerException.StackTrace + Environment.NewLine);

return tiex.InnerException;
}



Given the description of what happens during remoting above none of that should come as a surprise. All of the action takes place in the AdjustedRealException helper method. We are using reflection to get access to a private field of the Exception class (_remoteStackTraceString). We then take the value of stack trace from the inner exception (our real exception, remember, the one we want to keep), append a newline to it and push that value into the _remoteStackTraceString field of the inner exception. Lastly we return the inner exception and then rethrow it (in the caller).



When we run this version we get exactly what we wanted:




System.Exception: Actual Issue

   at ConsoleApplication1.Foo.Bar() in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 55


   at ConsoleApplication1.Program.Execute() in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 37


   at ConsoleApplication1.Program.Main(String[] args) in D:\Research\TheQuestion\ConsoleApplication1\Program.cs:line 15








Programmatic Debuggery


OK last one I promise and it’s a quick one. The tool I am working on requires some command line stuff to get it going. I can’t be bothered faking that up at the moment for when I want to debug a particular issue (especially as I already have a batch file that feeds in the data I need). That’s when I found System.Diagnostics.Debugger.Launch().



Calling this method in your code will essentially raise a breakpoint, load a debugger and put you in the surrounding method right after the call. Life saver if, for whatever reason, you need to hit a breakpoint but for some reason you can’t start the app under the debugger.



If you are still reading this then you deserve some kind of prize so here is a link to what I’ve been working on. More soon.

Sunday, 19 April 2009

Book Review: CLR via C# (2nd Ed)

CLRviaCSharpCover Once in a while you come across book that you wish you had read earlier in your career but recognise that you probably would not have been able to take advantage of it without many years of experience. CLR via C# by Jeffrey Richter is one such book.

Instead of trying to teach you about a particular language this book takes you on a guided tour of the .NET Common Language Runtime (CLR) and uses the language specifics of C# to show how these concepts relate to your day to day job. If you don’t know the specifics of C# I think you’d have a hard time wrapping your head around what is going on and the author takes the time to explicitly state that a fair amount of C# (and OO design) knowledge is assumed. It’s difficult for me to say as I approach the book with many years of software development with C# behind me.

Don’t let the C# take your attention from the real matter at hand in this book though. This is a book about the CLR. In it’s pages you will learn:

  • The history and goals of the .NET framework
  • The individual components of an assembly. How they are signed and loaded.
  • What an AppDomain is and what services it provides.
  • How types are loaded and accessed at runtime
  • How events and properties are implemented (this was a highlight for me)
  • How generics works (do you know the difference between an open and closed type?)
  • Advanced Multi-threading scenarios
  • And more. Much much more

I feel as if I have learned hundreds of little bits of useful information reading this book. I can remember a few times in the past when a nugget of gold from this book could have saved me a lot of time and heartache and I can imagine a few scenarios in the future where I will be fore-armed against weird CLR edge cases.

The writing style is interesting and engaging despite the dry subject matter. The author is obviously extremely familiar with the framework and the decisions that shaped it into it’s current form. He’s also confident enough in his knowledge to call out what he feels are mistakes or areas for potential improvement. This commentary gives you a glimpse into the framework of the future or perhaps into the framework of an alternate reality.

Despite Jeffrey’s style the subject matter makes this a very dense and at times difficult to understand book. Some sections left my head spinning and required multiple readings before I was satisfied that I could move on. I don’t recommend this book for people that are just starting out in the .NET space nor do I recommend sitting down with it on a lazy Sunday afternoon and trying to read it from cover to cover. For those who’ve been in the game for a while though this book is a must. It won’t force you to make any fundamental changes to the way you write .NET software but it will help you to fine tune your understanding and turn a pretty good developer into an excellent one.

NOTE: The 2nd edition of this book (which is the one I read) is written for the 2.0 version of the CLR. Despite the fact that C# (the language) is up to version 3.0 and the .NET Framework is up to version 3.5 the CLR is still version 2.0. That means that the 2nd edition is current and a new edition is not to be expected until a new version of the CLR is released. Jeffrey addresses this issue in his own blog post.

If you are in Australia the best way to get a copy of the book is to order it online from MS-Press Australia. That way it gets shipped out of Sydney instead of from another country. They’ll even price match Amazon and if you order before 1st May you go into the running to win some stuff! 

In the interests of full disclosure I was provided a free copy of this book in exchange for a review. I have not allowed that fact to influence my comments in any way. I am not affiliated with MS Press or MS Press AU and I don’t get any kind of commission for a sale.

Wednesday, 1 April 2009

Perth ALT.NET April - Test Driven Dojo

Next week is the 3rd meeting of the Perth ALT.NET group. For this meeting we thought we'd host an event where anyone can come along and participate. Specifically, we are having a Coding Dojo.

A Coding Dojo is a place where software developers can get together to practice a specific technique or technology in order to share and improve their skills. This one is focussing on Test Driven Design.

On the night you will get 10 minutes or so of explanation from a presenter and then you'll get the opportunity to sit at the keyboard with your favourite technology and implement some stuff in a test-first way under the guidance of the facilitator.

We have sessions on MOSS, WinForms, ASP.NET and Silverlight lined up so there should be something for nearly everyone.

When: Wednesday 8th April, 5:30pm until late (we'll kick off around 6ish)
Where: 43 below restaurant and bar - 43 barrack street, perth
What: Perth ALT.NET April - Test Driven Dojo
Cost: Free**

If you plan on attending we'd really appreciate you registering here. To keep track of what's happening in the Perth ALT.NET group you might want to check out http://perth.ozalt.net

Also don't forget the Perth .NET Community of Practice meeting is tomorrow (Thursday) night. Hope to see you next week.

** Doesn't assume your time is worthless as you'l be hanging out in a pub.