Marking public interface/method as not yet implmented

[rbr]

I have a problem that I am looking for a clean way to solve.
Currently, we provide interfaces as public apis for our internal
customers to consume. However, we may build and deploy an entire
interface that may take several iterations to fully conplete. For
example, say we have an IBankingSvc that has a save, selectbyid,
select by name and a delete method. We auto-gen the interface and
implement the underlying code for the save and selectbyid methods in
our first iteration. When we deploy this code for consumption by our
internal clients, we currently use XML comments to indicate the
selectbyname and delete methods are not yet implemented.

Not suprisingly, this is not always sufficient for the consumers of
our API. Is there a nice way to mark these methods say, with an
attribute, that would either hide these methods or clearly mark them
as not implemented? I am not familiar with a way to accomplish this
and would greatly appreciate a more graceful sulution.

Thanks in advance for any ideas or suggestions.

rbr

[Paulo Roberto Pellucci]

I guess your point is beyond the use of interfaces. Since interfaces is a contract and it will only allow public methods, shouldn't you be using just a class or, maybe abstract class?

--
Atenciosamente,
Paulo Roberto S. Pellucci

[Cerebrus]

I think this is a perfect example of the correct use of Interfaces in
the context of modules under active development. It allows consumers
to interact with the public interface regardless of the state of
internal implementation of functionality. Abstract classes are not the
solution, in this case.

I think "rbr" should clarify exactly what other metadata are the
consumers of the API looking for ? XML Comments are a good way to
indicate that the functionality is not yet implemented. I don't
recommend using the NotImplementedException route because that is a
runtime evaluation method.

You could define your custom attribute (such as
"NotImplementedAttribute") but the consumers of the API need to have a
way to evaluate at design time what that attribute entails.

On Nov 6, 7:05 am, Paulo Roberto Pellucci <paulo.pellu...@gmail.com>
wrote:

> Paulo Roberto S. Pellucci- Hide quoted text -
>
> - Show quoted text -

[Arsalan Tamiz]

How Cerebrus? I don't understand why he is talking about "interface". And following is also confusing,

"We auto-gen the interface and implement the underlying code for the save and selectbyid methods in our first iteration"

Generating the interface and then implementing the underlying code? Implementing where? obviously in some Class. Which means they are providing the class to clients NOT interface.

And to make it simple why putting the methods if we haven't implemented them yet?

[Cerebrus]

Arsalan,

Please find my comments inline with your post. Ryan, please provide
inputs to this discussion.

On Nov 6, 3:17 pm, Arsalan Tamiz <sallus...@gmail.com> wrote:
> How Cerebrus? I don't understand why he is talking about "interface". And
> following is also confusing,
>
> "We auto-gen the interface and implement the underlying code for the save
> and selectbyid methods in our first iteration"

Because it appears that the API needs to *fix a contract* with the
API's subscribers so that the latter can begin usage of both those
parts of the code that have been implemented as well as the members
that will be implemented in later iterations with the certainty that
this public semantic contract will not be changed. Most people seem to
think of interfaces as only useful for multiple inheritance, but they
often don't realize that this example provided by Ryan is probably the
best real world example of a situation where an Interface would be
almost indispensable.

> Generating the interface and then implementing the underlying code?
> Implementing where? obviously in some Class. Which means they are providing
> the class to clients NOT interface.

It is a common procedure to generate an interface and then implement
the underlying code. In this case, it is almost certain that the API's
subscribers interact almost exclusively with the public interfaces of
the API, not the internal classes.

> And to make it simple why putting the methods if we haven't implemented them
> yet?

Try to envision what the OP is saying... Let's say, You are developing
a library full of useful functionality. The problem is that another
team is writing code that will use your library *at the same time*. In
order to be able to do this, you need to fix a contract with the other
team that freezes the public interface of your library. After that,
they do not need to care (and pester you!) about the progress of each
part of your library.

I may be wrong about this whole thing, but I hope that I have
understood Ryan's situation correctly.

[Arsalan Tamiz]

As per my understandings "interfaces" are used in polymorphism NOT multiple-inheritance. Thus the given scenario is NOT an ideal case for interfaces.

In my opinion "NOT Implemented" approach is like a workaround. The better approach is to break the functionality into smaller chunks and then combine them.

If a team is working on a Library then whole library should be broken into full functional smaller parts. Each part should be independent as far as its own functionality is concern. Latter they can be combine to have the desired set of work done. And yes each individual team will be using "interfaces" to provide the "socket" for other classes to "plug in". But again NO need for "NOT implemented" approach once both parts are completed just "plug in".

I think the best practical example is Drawing application, where one team works on page lay-outing module, other team works on drawing objects. Both are independent. The page lay-outing class asks a "shape" interface to draw it on page. The drawing object will always implement this "shape interface" and will be responsible for drawing itself.

A real world example,

In cars we are provided with a sound system "interface", any sound system which implements that "interface" can be plugged in and will be called a compatible sound system. The car manufacturer's responsibility is to create that interface and back-end of sound generation and does NOT need to work on different audio formats. While the sound system's responsibility is to implement that interface and to get the data from device and pass it through interface. In short sound system is responsible to work on different audio formats.

So in above case one company can create a sound system which can only play Audio CD while other company can create a sound system which can NOT only play Audio CD but can also play MP3, etc. formats.

[rbr]

Cerebus,

You are spot-on with your interpretation of my situation. I apologize
for not being clearer. However, you obviously have experience using
this implementation of interfaces as you intuitively picked-up on my
needs.

So, to reiterate, I have an interface that acts as my contract which
my subscribers consume. The concrete implementation of the code
actually lays in another class that implements the interface. (I
highly suggest that any developer not familiar with this use of
interfaces investigate it further. This works wonderfully in the
scenarios you describe.) As we are an agile team that may or maynot
get to implementing the concrete implementation during a given
iteration. However, we do need to publish this contract to our
consumers for use so they can begin developing against it.

The problem that I have been trying to solve was to explicitly call
out, at design time, that a given method is not yet implemented. The
current solution is great for the developers that know to look for the
not-implemented comment. However, in a large organization, this is not
always the case. We have been using the NotImplementedException to
prevent any misleading code to slip through the cracks. It gets caught
in unit tests if not before. However, I agree this is not ideal.

This is precisely why I would like to find a solution that will likely
still include the XML comments. However, I was hoping to be able to
either create a compile-time warning or, if needed, a compile-time
error. Off the top of my head, I cannot think of a way to do this and
have not been able to locate any resources online that explain a
resolution to this situation. If there is not one, we will stick with
the documentation and just keep reminding people to pay close
attention to the documentation.

I had no idea that this little question would spark such an
interesting conversation. Thank you all for your comments.

TIA

rbr

> > > way to evaluate at design time what that attribute entails.- Hide quoted text -

[Peter Smith]

On Fri, Nov 6, 2009 at 10:57 AM, rbr <ryank...@gmail.com> wrote:

This is precisely why I would like to find a solution that will likely
still include the XML comments. However, I was hoping to be able to
either create a compile-time warning or, if needed, a compile-time
error. Off the top of my head, I cannot think of a way to do this and
have not been able to locate any resources online that explain a
resolution to this situation. If there is not one, we will stick with
the documentation and just keep reminding people to pay close
attention to the documentation.

What's wrong with doing:

public override void ReallyHardMethodToImplement()
{
       #warning ReallyHardMethodToImplement() is not yet implemented
       throw new NotImplementedException("ReallyHardMethodToImplement() is not yet implemented");
}

Shows up at compile time, shows up at run time, doesn't break anything else, easy to remove.

[Peter Smith]

On Fri, Nov 6, 2009 at 12:16 PM, Peter Smith <psmit...@gmail.com> wrote:

What's wrong with doing:

Oh, wait, I bet you're not letting your end users compile your code, are you?

Darn non-open source projects....

[rbr]

Lol! Yeah, my end users are all internal currently. However, they
still do not touch my code! ;)

rbr

On Nov 6, 10:17 am, Peter Smith <psmith.w...@gmail.com> wrote:

[Peter Smith]

So, you don't want to generate a compile-time warning, you want to generate a link-time warning.

Hrm. Is there any access at all in this environment to link-time actions?

Make them run a Static Analysis tool? :)