Which kind of method signature do you prefer and why?

Question

Ok, this is probably highly subjective but here it comes:

Let's assume I'm writing a method that will take a printscreen of some region of the screen. Which method signature would you prefer and why?

1. Bitmap DoPrintScreen(int x, int y, int width, int height);
2. Bitmap DoPrintScreen(Rectangle rect);
3. Bitmap DoPrintScreen(Point point, Size size);
4. Other

Why?

I keep seeing myself repeatedly implementing both 1) and 2) (redirecting one of them to the other) but I end up usually just using one of them, so there really is no point in having both. I can't decide which would be better. Maybe I should use the signature that looks the most with the method I'll be calling to make the printscreen?

Answer 1

Rectangle is probably the most clear because the argument does not depend on the position. It would be easy for a user to accidentally swap x and y or width and height.

Point/Size is also better than x-y-width-height, and sometimes the extra explicitness can be a little more clear to read.

But ultimately, there's no good reason to not use all three overloads.

Answer 2

It depends. If this is a library for general use, by all means add all three. The .NET framework, especially GDI+, is full of examples of this. If the conversion is trivial, it's not much effort, and your users will be thankful.

If it's just an internal class, I'd go for the option that is easiest to use from the call site. For example, if the caller already has a Rectangle available, the Rectangle overload is better. If there are multiple call sites with different preferences, it's probably better to add multiple overloads as well.

Answer 3

I think you should select the version that maps best to the other methods that would be used in conjunction with your code. I am referring to .Net methods and methods from other standard or common 3-rd party libraries. In that way the code looks uniform and the same objects can be passed to other methods directly.

Answer 4

Rectangle best describes the behavior of the function (at least I hope it does!) The X & Y associate with width & height so as to define a rectangle; they are not arbitrary unrelated variables.

Answer 5

I would go with 2)

Bitmap DoPrintScreen(Rectangle rect); 

As mark said the parameters can be swapped in the following:

Bitmap DoPrintScreen(int x, int y, int width, int height); 

I wouldn't choose this as it is not as explicit as 2) to someone else reading it. Whereas there is no ambiguity to someone read 2)

Bitmap DoPrintScreen(Point point, Size size);

Of course that's just my opinion of course!!!

Answer 6

I would personally include the three of them, letting the user choose which one she/he prefers to use, all to offer the most freedom of use possible to the user. No one likes to be handcuffed. Well, not in programming! ;)

Answer 7

If you only end up calling one of these overloads, then there's really no point in having the other two sitting around. There's nothing I hate more than having to sift through 27 overloads of some method, hoping that a) I find the right one for my purposes, and b) the person who wrote this mess actually ran and tested the overload I'm using even once.

In the specific case of a screen-capture method, the overload with the Rectangle parameter would probably be the most handy, since forms always have a rectangle associated with them. Also, if you need to grab the same screen area repeatedly, it's easier to save one variable (a Rectangle) than four (x, y, width and height).

Answer 8

I would provide all 3 if it would be convenient for the consumer. After all, your actual implementation will (or should) only exist in one place. All of the other overloaded methods will simply extract the appropriate parameters and pass them to the local method with the actual code.

...so it's a convenience for your users with little to no effort on your part. Win/Win.

Answer 9

Both - 1 and 2. And also one without params for full-screen =)

Some times you have separated x,y,width, height, some times you already have rectangle. Varian 3 - IMHO is very rare =) But user always can convert values to rectangle, or break apart rectangle to values) I think this is philosophical question.

So make them all or pick random one )))

Answer 10

The best one is

Bitmap DoPrintScreen(Rectangle screenArea);

If you think about the method parameters as being part of a "concept", in this case the concept of a screen area, then the other options don't abstract that concept nicely enough.

Also, use a good name for the parameter, because it might make calling code even more clear by the use of named parameters in C# 4.0.

Answer 11

All 3. Like you said, you're going to redirect them to 2 any who so, why not keep all three? I do think you should change the Rectangle parameter name to something more meaningful - like printArea.

cheers.