High maintenance

High maintenance

Rate This
  • Comments 46

The other day I went to buy some snack from the snack machine in the kitchen. The snack I wanted was in slot B-10, so I put in my coins, press B - one - zero, hey wait a minute there's no zero button! And why is it serving me up the snack on the left end of the machine instead of the right? Aha, there is a button marked "10", which is the one I was supposed to press. Instead I got snack B1. How irksome!

And then I laughed at my plight, because of course Steve Maguire told the same story about Microsoft vending machines in Writing Solid Code fifteen years ago. Maguire went on to make an analogy between bad candy machine interfaces and bad software interfaces; a "candy machine interface" is one which leads the caller to make a plausible but wrong choice.

Coincidentally, I was asked to review a fragment of code recently that got me thinking again about candy machine interfaces. This isn't exactly the kind of bad interface that Maguire was talking about -- but I'm getting ahead of myself. Let's take a look at the code:

public static class StreamReaderExtensions
{
    public static IEnumerable<string> Lines(this StreamReader reader)
    {
        if (reader== null)
            throw new ArgumentNullException("reader");
        reader.BaseStream.Seek(0, SeekOrigin.Begin);
        string line;
        while ((line = reader.ReadLine()) != null)
            yield return line;
    }
}

The idea of this code is awesome. I use this technique all the time in my own programs when I need to manipulate a file. Being able to treat a text file as a sequence of lines is very handy. However, the execution of it has some problems.

The first flaw is the bug I discussed in my earlier post on psychic debugging. Namely, the null check is not performed when the method is called, but rather, when the returned enumerator is moved for the first time. That means that the exception isn't thrown until possibly far, far away from the actual site of the error, which is potentially confusing.

The second flaw is that the "while" loop condition is a bit hard to read because it tries to do so much in one line. Shorter code is not magically faster than longer code that does the same thing; write the code so that it is maximally readable.

But there's a deeper flaw here. To get at it, first let me state a crucial fact about the relationship between a stream reader and a stream:

A StreamReader “owns” its underlying stream. That is, once a stream has been handed to a stream reader by a caller, the caller should not muck with the stream ever again. The stream reader will be seeking around in the stream; mucking around with the stream could interfere with the stream reader, and the stream reader will interfere with anyone trying to use the stream. The stream reader emphasizes its ownership by taking responsibility for disposing the stream when the stream reader is itself disposed.

Now, “Lines” defines an object, and what does that object do right off the bat?  It mucks around with the underlying stream. This is big red flag #1. This smells terrible. No one should be messing with that stream but the reader.

Furthermore, think about it from the caller’s point of view. Maybe the caller knows that there are a bunch of bytes that it wants to skip, so it deliberately hands a StreamReader to Lines() which has been positioned somewhere past the beginning of the file. But Lines() thinks that it knows best and ignores the information that the caller has given it. This is big red flag #2.

(The reason why the original code was seeking back was because the same reader was being "recycled" many times to read the same file over and over again, which is yet another red flag. Readers are cheap; you can have multiple readers on one file, there's no need to hoard them and reuse them.)

The third big red flag for me here is the ownership issue. When you hand a stream to a reader, the reader takes care of everything for you from then on – that’s the “contract” between the reader and the caller.  “Lines()” does not have that contract. Lines()’s contract says “attention caller: I am taking ownership of this reader. I am going to muck with its underlying stream. You must never use this reader for anything ever again – except that I’m not going to dispose it for you. If you want the reader and its stream closed then you are going to have to keep a reference to it around until you can prove that I am done with it. And if you get it wrong, either I crash or you get a resource leak. So get it right.”

This is a terrible contract to impose upon a caller, and of course, the imposition here is in no way represented by the signature of the method. You just have to know that “Lines()” owns the reader for the purposes of all its functionality, but not for its cleanup, which is deeply weird.

In short, the caller needs to know all the details of what is happening in the method in order to use it correctly; this is a violation of the whole purpose of creating methods. Methods are supposed to abstract away an operation so that you do not have to know what they are doing.

A fourth red flag is that the task performed by Lines() does not have a clear meaning in terms of the logic of the program. In looking at every caller of this method it became clear that the desired semantics were “give me the lines of this text file one at a time”. But we haven’t written a method that does that. In order to get the lines of a text file from Lines() the caller is required to do all kinds of work to make Lines() happy – open the stream, create a reader, call Lines() but keep the reader around, close the reader after we know that the iterator is done.

This code makes the caller do a whole bunch of things -- things that have to be done in exactly the right order but potentially distributed out over long stretches of time and disparate code locations. This method is very "high-maintenance"! Everything has to be just right all the time in order for it to be happy and get along with others; anything out of place and things will start going wrong.

Finally, we have an example of premature generality here -- if the intention is to read a text file, then write a method that reads a text file. If you don't need the power of reading lines from an arbitrary stream, maybe don't implement that. Cut down on your testing burden.

Some relatively simple changes fix it up:

public static class FileUtilities
{
    public static IEnumerable<string> Lines(string filename)
    {
        if (filename == null)
            throw new ArgumentNullException("filename");
        return LinesCore(filename);
    }
    private static IEnumerable<string> LinesCore(string filename)
    {
        Debug.Assert(filename != null);
        using(var reader = new StreamReader(filename))
        {
            while (true)
            {
                string line = reader.ReadLine();
                if (line == null)
                   yield break;
                yield return line;
            }
        }
    }
}

And now everything is crystal clear. The purpose of this thing is to read the lines out of a text file. The caller gives it the name of a file, it gives you the lines, and we’re done. The caller does not have to worry about anything else – the iterator takes care of opening the file, cleaning up when its done, and so on. There’s no messing around with streams at all; we have now provided an abstraction over the file system to the caller.

Whenever you write a method think about the contract of that method. What burdens are you imposing upon the caller? Are they reasonable burdens?  The purpose of a method should be to make the caller’s life easier; the original version of Lines() makes life harder on the caller. The new version makes life easier. Don't write high-maintenance methods.

  • What's wrong with this code, part II

  • About the "while ((line = reader.ReadLine()) != null)" line, we would not need such a hack or the awkward code you posted if the method was better designed, for example:

    bool ReadLine(out string line)

    which gives

    string line;

    while (reader.ReadLine(out line))

    {

     yield return line;

    }

  • I disagree with the "ownership" idea in this case and in many Stream scenarios similar to this. BinaryReader "correctly" takes ownership of the stream and closes the stream when you're done with the BinaryReader. But sometimes you just need BinaryReader functionality for a subset of the stream. If that's you're secenario you're out of luck--you have to reimplement BinaryReader! That's the greater of the evils.

  • So Brennan, your suggestion is that the frameworks designers ought to make the 99% likely common case difficult and bug-prone so that the 1% rare case works more easily?

    An important principle of frameworks design is that the people doing weird stuff should be the ones writing the goofy code. The people doing normal stuff should be given implementations that are not bug-prone.

    That said, I also disagree completely with your claim that the only alternative is to reimplement the reader. Were I faced with such a 1% scenario, I'd just implement a thin "no dispose stream" that wraps the underlying stream, but does not pass along the call to dispose. You want to make a binary reader that doesn't dispose the stream, you just wrap the stream in your 'no dispose wrapper' and hand that thing to the reader. When the reader disposes the stream, that's a no-op and the underlying stream lives on. That seems a lot easier than re-implementing the reader.

     

  • General Comparing .NET IoC Frameworks Part 1 : Andrey Shchekin takes a look at 6 of the most popular IoC frameworks available for .NET. Comparing .NET IoC Frameworks Part 2 : The continuation of Andrey Shchekin's IoC shootout. High Maintenance Code :

  • I'd discourage this type of code in production systems for maintainablity reasons as it fails the Monday morning, I did not get any sleep the night before and my brain is dead, code understandable test.

    It hides its purpose which is to facilitate forward movement line by line through a text file.

    Cute code like this is OK when used one or a few times in an application, but damages the maintainability of a large application with many hundred of different examples of cute tricky code.  

  • Excellent discussion.

    Please don't let the pointy-haired boss have the last word.

  • You've been kicked (a good thing) - Trackback from DotNetKicks.com

  • Somehow my comment was lost. I like your solution so much that I documented it as a pattern, see community content at http://msdn.microsoft.com/en-us/library/65zzykke.aspx

    cheers

  • Nice, thanks!

  • A StreamReader / StreamWriter taking ownership of a Stream just seems wrong. Methods and classes should not be responsible for cleaning up resources that they didn't create, unless this is clearly documented and obvious.

    For example, the following looks like it should work, but fails unexpectedly with an ObjectDisposedException on the call to Seek:

    using (var s = new MemoryStream(capacity))

    {

       using (var writer = new StreamWriter(s))

       {

           Render(writer);

       }

       s.Seek(0L, SeekOrigin.Begin);

       using (var reader = new StreamReader(s))

       {

           return reader.ReadToEnd();

       }

    }

    Since the caller created the Stream, it should be the caller's responsibility to close it.

  • In this carnival there&#39;re a lot of software design/patterns and frameworks a bit of SOA, UML, DSL

  • I know this is an old topic but I'm really confused regarding why a reader or writer should close the stream itself..

    If I had to create a reader or writer in a way that the reader had to aquire the stream itself, then I would expect the reader to handle cleaning it.. but personally I don't see the readers job as aquiring the stream.. I see that as maybe helper methods.

    It makes completely sense that the solution should be

    using(var stream = .. aquire stream ..)

    {

     using(var reader = new StreamReader(stream))

     {

       .. do stuff..

     }

     stream.Close();

    }

    I certainly wouldn't be expecting the stream to close the stream.. the reader didn't get the stream, I gave it the stream, so I will dispose the stream as well, thats my contract in the code...

    It seems to go against seperation of concerns, reader becomes somewhat of a 'jack of all trades'.. hey guy don't worry - I'll close the stream when you're done, because thats generally what you want no?

    The code I wrote makes much more sense.. whos doing what.. I'm getting a stream.. I'm reading over the stream.. I'm closing/disposing the stream..

    I agree changing .net now is impossible, the amount of code written thats now expecting this behavior.. but I'd go as far as classifying this in the relms of the clr array.. oh did you guys know i do unsafe invariance as covariance as well? (echoing off)

    nooooooooooooo!

  • The other day my charming wife Leah and I were playing Scrabble Brand Crossword Game (a registered trademark

  • Hi Eric,

    Sorry to respond to such an old post. I was triggered to go here from your Scrabble post :-)

    I am working on an extension library (nxl on codeplex) and am struggling with this one. I came up with the following code but am not sure if its very usable:

         public static IEnumerable<string> StreamLines(Func<Stream> streamConstructor)
         {
           using (Stream stream = streamConstructor()) {
             using (var sr = new StreamReader(stream))
             {
               while (true)
               {
                 string line = sr.ReadLine();
                 if (line == null)
                   yield break;
                 yield return line;
               }
             }
           }
         }

    The ownership issue is solved this way but usage is a bit clunky:

           foreach (string line in StreamExtensions.StreamLines(() => File.Open("C:\test.txt", FileMode.OpenRead)))

    It not even an extension any more :S

    Does it make sense to go this road?

    Regards, Jacco

    Ah, you are using lambdas to implement lazy evaluation of the stream opening. Is that so that if someone takes out an enumerator and then sits on it without moving it, the file open doesn't happen until the first line is requested? That's pretty clever. A bit clunky, and perhaps a bit TOO clever, but neat. I like it from the point of view of a mechanism that solves this problem.

    However, from a usability standpoint, it's pretty taxing. If the method "StreamLines" is intended to take a stream and return some lines then it should take a stream and return some lines. Your "lazy evaluation" feature imposes a "tax" on ALL users of this method, not just the users who want to take advantage of the feature.

    What I might do in this case is write two extension methods, one that takes a stream, one that takes a func<stream>. Then you can decide which one you want to use and don't have to pay a tax if you don't want laziness.

    Another way to attack the problem would be to make a new subtype of Stream called LazyStream. A LazyStream takes your Func<Stream>, and then forwards all calls to the lazy evaluated stream when asked. The user can then create a LazyStream if they want to have a stream that isn't opened until its needed.

    -- Eric

     

Page 3 of 4 (46 items) 1234