Short sentences as names of interfaces

I've always disliked that rule (most coding standards I saw, had such a rule) about starting names of interfaces with "I". It feels like the Hungarian notation is back. And I found myself using that leading "I" in such a way that the letter really means something. For example, instead of IInputValidator, I would create an interface named IValidateInput. This is a very reader-friendly name, in my opinion: it doesn't force you into using a word that doesn't really exist ("validator" is, obviously, a verb turned into a noun; it's not in the dictionary, according to Merriam-Webster). Also, this name explains what the implementer does, and explains in a natural way. "What is your responsibility?" - you ask the interface. "I validate input", - it replies.

Of course, all of the above applies only if the interface describes something that does one thing. In general, I prefer nouns and adjectives when naming interfaces.

Countdown Latch, take #1

OK, enough ranting. It's time to post something useful. Here is a Countdown Latch I wrote some time ago. A countdown latch is a thread-safe object that has a counter associated with it. The latch allows threads to block until that counter -- you can only decrement the counter -- reaches zero. I always missed it in .Net FW, and one is going to be in FW 4 -- finally!

(UPDATE: of course, only after writing this I've discovered an easier solution -- one using Monitor.Wait() and Monitory.PulseAll()).

Here is the listing:

using System;
using System.Globalization;
using System.Threading;

namespace Primitives.Threading
{
    /// 

    /// A thread-safe counter (goes only down) that is capable
    /// of blocking threads until the counter's value reaches zero.
    /// 
    public class CountdownLatch : IDisposable
    {
        private int currentCount;
        private ManualResetEvent countHasReachedZero = new ManualResetEvent(false);
        private object disposalCriticalSection = new object();
        private ManualResetEvent allWaitingThreadsAreGone;
        private const int MaximumNumberOfWaiters = int.MaxValue - 1;

        /// 

        /// Note: it's safe to access/manipulate the value of this
        /// field only under a lock for disposalCriticalSection,
        /// or using the Inrerlocked methods.
        /// 
        private int numberOfWaitingThreads;

        private bool disposed;

        public CountdownLatch(int initialCount)
        {
            if (initialCount <= 0)
                throw new ArgumentOutOfRangeException(
                    "initialCount",
                    "Must be greater than zero.");

            this.currentCount = initialCount;
        }

        /// 

        /// Decreases the latch' counter value by one.
        /// Does not throw, if the count has already reached zero.
        /// 
        /// 
        public void Decrement()
        {
            lock (this.disposalCriticalSection)
            {
                this.MakeSureTheLatchHasNotBeenDisposed();

                if (this.currentCount > 0)
                {
                    this.currentCount--;

                    if (this.currentCount == 0)
                    {
                        this.countHasReachedZero.Set();
                    }
                }
            }
        }

        /// 

        /// Current latch counter value.
        /// This is for informational purposes only.
        /// 
        public int CurrentCount
        {
            get
            {
                return Thread.VolatileRead(ref this.currentCount);
            }
        }

        /// 

        /// Blocks the calling thread until the latch count becomes zero.
        /// 
        /// 
        /// 
        public void WaitUntilCountIsZero()
        {
            lock (this.disposalCriticalSection)
            {
                this.MakeSureTheLatchHasNotBeenDisposed();

                this.IncrementNumberOfWaiters();
            }

            try
            {
                this.countHasReachedZero.WaitOne();

                this.ThrowIfHandleHasBeenSetByDispose();
            }
            finally
            {
                this.DecrementNumberOfWaitersSignalingTheHandleIfDisposing();
            }
        }

        /// 

        /// This is an insane precaution: even having that many threads is simply impossible.
        /// 
        /// 
        private void IncrementNumberOfWaiters()
        {
            this.numberOfWaitingThreads++;

            if (this.numberOfWaitingThreads == MaximumNumberOfWaiters)
            {
                this.numberOfWaitingThreads--;

                throw new InvalidOperationException(
                    String.Format(
                        "Cannot block - only as many as {0} waiting threads are supported.",
                        MaximumNumberOfWaiters));
            }
        }

        private void DecrementNumberOfWaitersSignalingTheHandleIfDisposing()
        {
            lock (this.disposalCriticalSection)
            {
                this.numberOfWaitingThreads--;

                if (this.disposed && (this.numberOfWaitingThreads == 0))
                {
                    this.allWaitingThreadsAreGone.Set();
                }
            }
        }

        /// 

        /// Blocks the calling thread until the latch' counter value
        /// is zero or specified amount of time passes.
        /// 
        /// Amount of time to wait for latch'
        /// counter value to reach zero.
        /// True, if the latch has signaled (counter reached zero)
        /// before specified Time Span elapsed; False, otherwise.
        /// 
        /// 
        /// 
        public bool WaitUntilCountIsZero(TimeSpan waitTimeSpan)
        {
            lock (this.disposalCriticalSection)
            {
                this.MakeSureTheLatchHasNotBeenDisposed();

                if (waitTimeSpan < TimeSpan.Zero)
                    throw new ArgumentOutOfRangeException(
                        "waitTimeSpan",
                        "Must be greater than TimeSpan.Zero.");

                this.IncrementNumberOfWaiters();
            }

            try
            {
                bool gotZero = this.countHasReachedZero.WaitOne(waitTimeSpan);

                if (gotZero)
                {
                    this.ThrowIfHandleHasBeenSetByDispose();
                }

                return gotZero;
            }
            finally
            {
                this.DecrementNumberOfWaitersSignalingTheHandleIfDisposing();
            }
        }

        private void ThrowIfHandleHasBeenSetByDispose()
        {
            lock (this.disposalCriticalSection)
            {
                if (this.disposed && (this.currentCount != 0))
                    throw new ObjectDisposedException(this.GetType().FullName);
            }
        }

        /// 

        /// Disposes of all unmanaged resources allocated by the latch.
        /// (The kernel objects used, are released).
        /// Also: releases all waiting threads.
        /// 
        public void Dispose()
        {
            bool needToWaitForWaitersToFallOff = false;

            lock (this.disposalCriticalSection)
            {
                if (this.disposed)
                    return;

                this.countHasReachedZero.Set();
                this.disposed = true;

                if (this.numberOfWaitingThreads > 0)
                {
                    this.allWaitingThreadsAreGone = new ManualResetEvent(false);
                    needToWaitForWaitersToFallOff = true;
                }
            }

            if (needToWaitForWaitersToFallOff)
            {
                this.allWaitingThreadsAreGone.WaitOne();
                this.allWaitingThreadsAreGone.Close();
            }

            this.countHasReachedZero.Close();
        }

        private void MakeSureTheLatchHasNotBeenDisposed()
        {
            if (this.disposed)
                throw new ObjectDisposedException(this.GetType().FullName);
        }
    }
}

FIFO, fairness and synchronization primitives

Recently I ran a few multithreaded tests to figure out whether FIFO principle (First In, First Out) is respected for ManualResetEvent, AutoResetEvent, ReaderWriterLockSlim or the Monitor. I'm glad to report: all those nice things mentioned above do not support FIFO.

Why bother with FIFO in the first place? Well, it's a question of fairness: say you have a ReaderWriterLockSlim (or any other primitive from the list above) along with 2 writers waiting for a lock, one of them has been waiting for a minute and a half, and the other one has been waiting for only 2 seconds -- are they really equal like ReaderWriterLockSlim assumes, or are they not? I think, in the scenario described, we should favor the writer that started waiting earlier. You can use queues to achieve just that (at least this is what I did). This applies to any synchronization primitive.

Monitor seems to be the nicest of all four: it behaves perfectly well in terms of FIFO on a single-CPU, single-core PC. However, this is not the case with Quad-core processors, for instance.

Moving in

This is my first entry here. I've just moved from http://idontwasteink.spaces.live.com/blog/ with all my entries.

Best class' description of all time

ConfigurationErrorsException class (.Net Framework) is described precisely this way: "The current value is not one of the EnableSessionState values". Very informative, to say the least. I think it's worth noting that this class is also not a Godzilla and not a Popsicle. Of course, we all make mistakes (I personally make dozens of them every day, and if it wasn't for TDD...), I'm just trying to stress the same old point: do not cipher your code, it's hard enough to read as it is. And misleading class' description can be nasty (although it's way worse to cipher names of classes).

Would not it be nice

T-SQL and the likes have disappointed me years ago. I'm not sure though what hurts readability more -- the wildcard star in "SELECT * FROM ...", or the tragically misplaced "WHERE" statement (e.g. "SELECT FirstName FROM ... WHERE..."). [Instead it could have been: "RETRIEVE DATA FROM MyTable INCLUDING/EXCLUDING (...set of filters goes here...)" -- I didn't give a lot of thought to this imaginary query, therefore, the language used may not be sufficient for defining any query on the planet, but, in my opinion, it's much easier to read and understand than the modern SQL counterparts].


"I'm used to reading/writing SQL statements the way they are being defined now, -- you might argue, -- And those statements make perfect sense to me!" Of course, it makes sense, but it's just another cipher you had spent some time breaking, memorized the ciphering/deciphering algorithm and voila: you understand SQL queries. Would not it be nice, if there were fewer ciphers (there are thousands in IT) to break and memorize? That would boost IT-productivity and make our work less complicated.

Sharp stuff

If something is math-related, it's unreadable. Long live C#, die F#, die LINQ. I ain't fucking touching anything with lambda in it.

ROI for WCF and WF

This spring I had a lot of time and no job. So I was lying on the floor, weighting the possibilities: I could become a bum, sell my yacht, dig deeper into Windows Workflow Foundation (WF), or I could go with Windows Communication Foundation (WCF). I had all the books I needed to decide -- three on WF, two on WCF. I carefully looked at those books, read all the introductions inside, and it became clear to me that WCF had a better return-on-investment (ROI). First, books about WCF are 20-30% thinner than those about WF (you invest less time). Second (you get more possibilities in return), WCF seemed to be more valuable for a whole lot of my possible employers: I think WCF-services will become no less popular than web-services pretty soon, and WCF is a unified platform (there are limitations) for building distributed applications. Those are in high demand these days.

WF, on the other hand, provides a unified platform for running and designing workflows, for automation of business processes. If you decide to spend time learning WF, you will end up with business process logic decomposed into workflows, which are made out of activities. If the design will be ok, you will be able to get the stuff automated with less software developers and more analysts. But it's not clear to me who would want to translate business logic from, say, pure C# to a well-designed workflow with corresponding activity libraries (let's assume those will also be created with C# code) -- the effort required to do the job is substantial. At the same time when you're migrating from, say, a web-service to a WCF-service, almost all code just stays the same in majority of scenarious.

I must also note that if you want to automate business-processes, all you need to know is C#. That's a great unified platform by itself. WF adds value, but increases costs, while WCF adds more, and it decreases costs, as it really provides a common model for coding distributed applications. WCF isolates you from excess information to a degree: you don't have to be intimately familiar with ASMX, WSE, MSMQ, IIS or whatever to start creating distributed applications, all you need is WCF (and an experienced architect). Therefore, WCF seems to be more newcomer-friendly and a great investment.

In short, I'm sure it takes longer to see the benefits of WF in action, than it is with WCF. I may be wrong, and I haven't covered all bases here, but that's what I was thinking while choosing between WCF and WF.

P.S.
Maybe WPF or Entity Framework, or another fancy new thing is great too, but it's out of my area of expertise. And for me it's one thing at a time.

P.P.S.
I had some experience with both WCF and WF, when I was lying on the floor.

Usage Errors and ArgumentException

I'm a bit defensive when I write software. I'm careful with the preconditions in every method and I always validate arguments of all methods. So I throw ArgumentExceptions a lot. The question is: should the code, which is calling into my code, catch and handle those exceptions or should it let the CLR kill the executing process by letting the exception propagate to the top of call stack unhandled? Many people say it's a good idea not to catch ArgumentExceptions, because those exceptions usually indicate usage errors, therefore, erroneous code must be recompiled, retested and reshipped. I am not sure about this idea being good. Why should everything crash if a method is has been called with improper arguments? The logic that acts as the argument guard must precede any business logic in a method, so if you get an ArgumentException it also says that there is no inconsistency in the system state (there is -- only produced by callers up the stack). So I catch ArgumentExceptions, log them, send error reports (optionally), recover from those exceptions (fixing inconsistency produced up the stack, if any) and continue running the application.


Yes, maybe you get an ArgumentException because a subsystem (a piece of logic, a function, a feature) is not working in the current release. So be it, maybe we should turn this failing feature off then? -- after we get a certain number of similar exceptions? Yes, this requires a bit of management, domain expertise, and some architectural effort, but I, as a user, fucking hate crashing applications.


Take a text processor for example. Imagine that every time you click «File->Save as…» in the menu, a usage error occurs, an ArgumentException is thrown -- should we close the application and report an error, or can we report the error and continue running the application? I vote for option #2: nothing critical has happened, and I would prefer either just logging the error, reporting it or blocking the erroneous execution path for the release (e.g. by disabling the menu item) to closing the app, losing the document that the user had been editing and then trying to recover it.


P.S. of course, there are ArgumentExceptions indicating that the application is unusable -- it depends on which component throws and under which circumstances.


UPDATE: I have changed my opinion three months after posting this. I do prefer to not catch ArgumentException-s.

Quote of the day

"Sometimes a toolkit class that's designed for reuse isn't reusable..." ("only because its interface doesn't match the domain-specific interface an application requires").

From my experience: class that's designed for reuse is rarely indeed reusable.

Or I can go even further: any class is barely usable.

The guideline, therefore, is this: do not use classes :P

kick #2

Here I'm continuing what I've started the last time. Coding: technical aspects, part #1 Everyone knows, there are best practices for handling exceptions. One of the design guidelines for exception-handling says: "Avoid handling errors by catching non-specific exceptions, such as System.Exception, System.SystemException, and so on, in application code." That's a great piece of advice (yes, you can never handle all the exceptions), as long as you don't use .Net Framework (.Net FW). One reason for this is you never know for sure which types of exceptions can be raised by the code (MSDN or intellisense not always help here, believe me, I've dug though some call stacks pretty deep just to get the exception types). There are other problems: 1) invoking same methods can produce different types of exceptions in different versions of .Net FW (see how the Mutex class behaves in v1.1 and v2.0). So if you're writing anything forward-compatible (that's you're planning to move to the next FW version someday), you'll have to retest every piece of Framework code for exceptions before actually migrating to the new FW. So some developers prefer catching non-specific exceptions and then filtering irrecoverable exceptions and throwing them no matter what -- this breaks another design guideline which says "Do not exclude any special exceptions when catching for the purpose of transferring exceptions". BTW, MS guys themselves do love filtering exceptions. 2) .Net FW throws exceptions of type System.Exception (WMI is written particularly badly and does just that in many places) -- how I'm supposed to _handle_ this ugly stuff in a nice way, I wonder? Therefore, most of the time we, developers end up either filtering exceptions by type (by throwing only some of 'em) after cathing the most general System.Exception or even worse -- not filtering and just catching. It's just impossible to do proper exception handling at a 100% in .Net FW at the moment. I see only one way through this mess: make all developers decorate every method with attributes which tell what types of exceptions the method throws (throwing SystemExceptions or just Exceptions must be prohibited).

A kick in the arse

Looks like the IT industry is going to take a break for tea and biscuits in coming years. And you know what? -- we sure as hell asked for this. We needed a major kick in the ass to get real, and here it is finally. Unreadable code What makes me think we're in deep shit? Well, I've worked on a few projects last 18 months for a large US company that loves to outsource, and I had to take a deep dive into some of .Net Framework's source code. Some of our projects we had to build over those projects other outsourcers had already completed. I've seen a lot of scary stuff (more on .Net later, in other posts), tons of barely readable texts. Yes, it's texts we're actually writing, guys, think twice about how you're gonna name your next class, next method, even next local variable. I'm sure that the vast majority of software developers is not even up for the job -- I mean crafting readable software not only takes a good developer, it takes one that has gut-feeling for simplicity, one that has his/her way with words, it might even take one that is not a developer at all. Right now maintainability of the vast majority of applications is lower than negative infinity. Make 'em usability tests if you're not sure you've created a good class (after the design meeting) -- drop a class diagram by your colleagues, make your manager approve this "time-waster", step up. I thought of giving a little (rather ill) example. Meant to tell you about how much time I've killed over a method which was named something like PrettyPrintAnErrorMessage(...) -- and it actually filtered exceptions inside, threw some kinds and swallowed others. The point of the story would have been: give a meaningful name to a method -- the one saying what the method _really_ does. I called that example rather ill because naming was not the only problem there -- it's just so not the way to handle exceptions (me and my guys had to do helluva job when we've found out about that _pretty_ printing). I decided to cut the story short because the computer science, the OO theory itself, C# language construct's names present some bigger issues. I'm gonna take the singleton pattern to make a point. You have to define the singleton as a class, right? But it's not a class at all -- a class is "a group, set, or kind sharing common attributes". You see where I'm going with this? The computer science, the OO theory, C# encourages us to write crap that only we understand, encourages by having a vocabulary where many words (like class) we might use in everyday life have odd meanings. By making the science's vocabulary (every science has one) simpler, by removing those cross-vocab intersections, we could make texts -- I mean code -- more readable. But it's a little late for that change, isn't it? The only thing we can do, as our part of the job, is to admit: we, software developers, are regular people, and so is the vocabulary we're using most of the time. Leave with it. No fancy names, just plain and simple stuff. I mean this: even the names of domain classes are to be reviewed if they're cryptic. Domain experts are regular people too, they may suck at giving names to things -- as much as we suck at naming classes today.

Starting up

Starting today I will be blogging about software development. I'll try to keep it short and up-to-the-point. Hopefully, somebody will find my notes helpful.