Contract-First or Code-First Design - Part 1 of a Conversation

Discussions

News: Contract-First or Code-First Design - Part 1 of a Conversation

  1. While in London for a conference, Ted Neward ran into Adrian Trenaman. Small talk – not the language - turned to a more interesting discussion of building Web services in general. Said Ted: "Learning WSDL is an exercise best reserved for the residents of the Fifth Circle of Hell." "You're not a fan of contract-first?" replied Adrian. A conversation on contract-first or coding-first ensued. From On The TSS Interop Blog:
    Adrian: (Laughter) OK, here goes. I used to think that WSDL was pretty ugly; it is certainly verbose and largely non-intuitive to the beginner. When I started with web services using XMLBus in 2001, the support for code-first programming was hugely attractive: you could take a Java class, run a simple “java-to-WSDL” utility, and an appropriate WSDL contract was generated. Today similar approaches exist for JAX-RPC toolkits like Axis, and JAX-WS toolkits, such as Celtix. These approaches allow developers to swiftly web-service-enable their existing code, with little or no need for WSDL design, and seem hugely attractive. Why would a developer want to venture into the “Fifth Circle of Hell” when they just don’t have to? I think the answer to this lies in the context of the service being designed. If this a tactical, short-lived service, then the code-first approach may be appropriate. However, if this service is to be long-lived within an enterprise, and engineered for reuse, then you may want to consider the following reasons to adopt a WSDL first approach. Ted: Well, you’re not saying anything I don’t disagree with so far: context always matters, no matter the technology. And frankly, I’m not advocating the “code-first” approach, either; I believe in something hybridized between the two, sort of a “code-first/contract-aware” approach. But why in Heaven’s name would you sign developers up to write 50 lines of obtuse XML that can’t be verified until runtime just to specify a contract that can be more succinctly expressed in four lines of Java or C#?

    Threaded Messages (19)

  2. Title ought to be ".. part 0.1 of a conversation" It is a potentially an interesting discussion, when it is actually posted.
  3. But why in Heaven’s name would you sign developers up to write 50 lines of obtuse XML that can’t be verified until runtime just to specify a contract that can be more succinctly expressed in four lines of Java or C#?
    Well, this question should be addressed to those scientists that conceived the WSDL.....I guess Contract-First vs Code-First ? It is sad that in 2007 there are guys discussing of this topic, without anyone realizing that with WebServices we are walking again on the same path followed by other technologies to bring them to maturity. Just to allow vendors to sell their old soup with a new brand. Guido
  4. Compiled Contract too?[ Go to top ]

    I welcome the discussion (but agree with the other comments that we really have none yet), but think we also need to look at the "compiled contract" as well as the other two options. http://www.webcohesion.com/compiled_contract.html
  5. waterfall model is dead[ Go to top ]

    Contract first assumes you are doing the waterfall model where you first figure out what to build, then how to build and then go about building & testing it. Sounded nice on paper when Royce wrote it down like that in the 60's but has been demonstrated to be a pretty bad idea since then. The problem is that most non trivial software development is non-linear in the sense that you tend to iterate and both the what and how part of what you are building is pretty much guaranteed to change substantially. If it is not changing, you are probably doing things wrong or you have a pretty boring & trivial software project. So committing to a contract early in the life cycle of building anything is a pretty stupid thing to do and goes against about 5 decades of experience with building software systems. Basically when doing interface design, you will get it wrong a couple of times before you get it right. WSDL lets you waste time on trying to get it right ahead of when you have the level of competence required to get it right. Additionally, WSDL sucks for anything else than machine generation/processing. It was designed for that and not for contract design and it shows. I know some computer science people have wet dreams of people doing pre/post conditions and writing formal documents & proofs. Hard reality is that software engineers don't do this. Recent trend is to generate web services based on code annotations and to make web services more message oriented. Of course the messages need to be described and there is various xml schema languages for doing so. XML schema (which WSDL depends on) happens to be one of the shittier ones for this.
  6. Re: waterfall model is dead[ Go to top ]

    It's not a simple decision of one is better than the other, as your melodramatic assessment of contract-first/waterfall being a "pretty stupid thing to do" implies. It all depends on the use case, which seems to be hinted at by the conversation snippet. First, there are integration efforts between parties that rely on an interface being written in stone because changes are not intended to be easily made. This even happens on "non trivial software development" efforts (question: how many developers would claim to be working on trivial software development efforts?). For such efforts, the logistics may simply not allow for a rapid iterative process, even though everyone might prefer that. Second, my opinion on contract-first is that it implies the ability to change the application code without breaking the interface. This can be achieved in multiple ways. You can deal with the incoming message directly and use the data in it to invoke an existing object. You have to write a little more code to make this work, but you gain the ability to change the object being invoked without breaking the contract (and the importance of that again depends on the use case). But there are other ways to accomplish that as well. So the question of contract or code first simply depends on the use case, and hopefully the linked conversation will delve into the tradeoffs and appropriate use cases for each. And anyone that tries to say one is "dead" or "stupid" can safely be ignored.
  7. Re: waterfall model is dead[ Go to top ]

    An iterative approach doesn't rule out contract first, what it does rule out is getting the contract right first-off, or before we start coding. Of course, the whole idea of an interface is that it should be separate from the implementation (you know what I mean). Perhaps we need a tool that allows us to design WSDL interfaces, not from the code, but from a higher-level perspective (i.e. not involving xml syntax). Perhaps, just a GUI tool to do this would help, so we can focus on the semantics of the interface not the syntx. Cheers, Ashley. -- Ashley Aitken Perth, Western Australia mrhatken at mac dot com
  8. Also when you generate the WSDL from the code, it generates the types and messages that get exchanged. This kind of exposes the internal data model of the application to the outside world (clients), that have to talk to the webservice using types that are specific to that webservice. Maybe a better strategy is to create some common data model for all applications to be integrated, and build upon that to create WSDL files as contracts between the different applications that need to be integrated. This way you have a common language between the applications, and also between the teams when discussing how the interface should look. This also buffers against changes when someone changes an object somewhere and re-generates the WSDL, breaking all clients in one step. This needs to be a bit more contained.
  9. Re: waterfall model is dead[ Go to top ]

    I agree with your comments. An iterative approach to the development of a contract really is the way to go. No matter how good a developer/architect who is establishing a contract for a service, he/she is still human, and would not be able to foresee the changing requirements. That's what we have learned from the past many years of software development. Also, I feel we have deviated a little from the contract approach to web services by focusing on a document (i.e WSDL) that really has meaning only in terms of the nature of the communication happening between two points on a distributed network. The contract really should have originated from a Use Case and should have stayed in that form throughout its lifecycle in a project. I am implying here that software tools/notations that one would use for modeling (UML based) should be naturally integrated into the process. UML Use case notation could easily be depicted in simple XML form and make for the origination of the contract. This Xml form then ties in with the design model as well as devoid of the semantic details of how these endpoints go about exchanging information (which is the information the WSDL provides). It does mean that the contract is much more high level than the WSDL as the document exchanged between two parties, but it is driven without the complexity of the WSDL and remains focused on the business aspect rather than the software aspect. Anyway, glad people are questioning the contract first-code first approaches. To me, there really is only one approach in today's scenario, that is - Iterative contract!! Amit
  10. Re: waterfall model is dead[ Go to top ]

    It's not a simple decision of one is better than the other, as your melodramatic assessment of contract-first/waterfall being a "pretty stupid thing to do" implies.
    My assessment is that waterfall model has never properly worked. People have been trying to fix it since the sixties. That's not a melodramatic assessment but an observation based on years of study of relevant literature and seeing companies find out for themselves that yes the waterfall model is a pretty naive way to approach any non trivial software development. No modern book on software engineering methodology actually recommends waterfall model development. They all describe it in their introduction of more appropriate development styles. And yes, people have been pretty stupid about this, it seems every generation of software engineers needs to find out in practice that doing things as the nice university professor explained in lesson 1 is a pretty good recipe for delivering the wrong stuff late. As for design by contract, it is heavily associated with getting requirements and design right before going into implementation (i.e. doing waterfall model type development). The whole point of iterative design is that it has been demonstrated over and over again that projects rarely get requirements & design right the first time. A proper iterative project will revisit all steps multiple times, including interface design. At some point some interfaces need to be frozen and generally you want to keep them frozen once they are frozen. Usually this happens when people start using the interface and its implementation(s) on a larger scale than just experimenting with it. After a few iterations, you'd expect the important stuff to stabilize somewhat and that is usually a good moment to (semi) freeze interfaces. Why wouldn't you want to change the interface? Until somebody is actually using it and terribly inconvenienced by any change, you should be able to change it at will. If somebody is using it, that implies code has been written already. In case the client code is written before the service code you actually are defining the interface client side. There's no fundamental problem with that. In that situation you are not designing a service interface service side but consuming the client side defined interface. That's not design by contract. Now there is the hypothetical situation where it is absolutely critical that client and service must absolutely rely on the fact that an interface never changes before either has been written. This happens but it is pretty rare that there is no way to negotiate changes in an interface. Contract first based development is based on the assumption that this both a normal and a desirable situation to be in. I disagree with both assumptions and will argue against anyone arguing otherwise.
  11. Re: waterfall model is dead[ Go to top ]

    +1 I totally degree. I've recently blogged on an idea by Gilad Bracha that takes the concept of change to the ulitmate conclusion. Code that changes whilst it is still running. So no need to restart your aplication to recieve updates over the web. Here is Gilads post: http://gbracha.blogspot.com/2007/03/sobs.html and my post: http://pab-data.blogspot.com/2007/04/look-mom-no-versions.html What we need are languages and tools that move away from a static fixed view of software as an artifact, to a view where software is seen as something dynamic which is continually changing. The web points the way forward I feel, and the success of HTTP (REST) IMO maninly comes down to the fact that it is a dynamic protocol that facilitates change.
  12. the intermediate solution[ Go to top ]

    I agree that writing WSDL and XML Schema is quite painful. At the same time, writing the contract first should be how you should write your web services. Starting with the code first, means that you cannot give the specifications to other parties until you start writing the code and if you want to have validation of your parameters (based on regular expression for example), you'll have your code full of annotations. The solution we did is to write the specification in a much simple format (still XML), and from this, we generate the WSDL (XML Schema included) and the Java code for the client and the server. We then put the project (XINS) on sourceforge with a BSD license. More info: http://xins.sourceforge.net/
  13. eh no[ Go to top ]

    I write the code first. Bang on the code, interface and the data it exchanges until I really like it and then, as a last step, freeze the interface. That's roughly the idea behind iterative development. You don't commit to contracts until the latest possible moment (generally when the software is released). After that people start using it and you are committed to whatever API you made available to these people. Naturally, refactoring WSDL sucks, which has tricked some people into thinking that you are supposed to get it over with ASAP. That's one of the many design flaws in WSDL and not an argument for contract first type development.
  14. Re: eh no[ Go to top ]

    I used to do it that way too. Problem was that if for example you have three other applications were using the same domain model. Doing it code first was imposing our own domain model onto these applications in addition to the one they were using to communicate, and some internal model they were probably using (one of them could be off the shelf for example). So instead, we extended the existing model, and write a WSDL using that domain model. We generated the data types and the interface of which we needed an to write an implementation. That also gives you freedom to change your own domain objects at will, because those are not the ones sent over the wire. In addition, I don't find refactoring WSDL that hard when you are using document/literal wrapped style. You just need to add/remove/change stuff in the input and output messages, or change their names. It's just basically just changing XML schema.
  15. Sounds no different than the debates in the '90s on whether to write your CORBA IDL first or your object impl classes first. Randy
  16. Contract first is a must for web services, because you don't want to expose the way your software is made inside, because you have to check if your schema is correctly understood by toolkits, etc. etc. But it doesn't mean you have to be stupid and never reconsider your contract during the development phase : your contract can change during development, but you change your contract, check it against your test suite, then change your code. Contract first doesn't mean waterfall development in the sense that nothing changes after specification. You can be agile, and make your contract before coding. Of course, the maturity of your contract depends on the maturity of your project : if you're building a web services front end to an existing system, you pretty much know what to do, and you likely won't touch your contract more than 1 or 2 times during development. If you're building a whole new product with a web service front end, well, your contract might change a lot...
  17. Contract first is a must for web services, because you don't want to expose the way your software is made inside, because you have to check if your schema is correctly understood by toolkits, etc. etc.
    These are technical issues that should be simple with the right tools, and by applying abstraction patterns when you need to. The hard part comes in the development practicalities, because developing a web service requires cooperation between several development teams, and often between several organisations. See below.
    your contract can change during development
    I have found that the agreement of a 'contract' between interoperability partners is taken - by business representatives at least, and sometimes by developers - to be binding, i.e. no contract re-negotiations. And I think that this ambiguity of 'contract' is the source of some of the sentiments on both sides of this conversation. As developers, most of us know deep down that you're very unlikely to specify the web service messages correctly the first time round; you will, during development, find a better way of doing things, or the requirements will move, or you have to add a parameter or two to a message. Yet there is a perception that once a web service contract is published it is fixed in stone, or that process hoops have to be jumped to make changes. This is exacerbated by the imperatives of the development process; as soon as a contract is out there, code is written to use it, and changing the contract becomes technically and practically difficult because more than one development team is involved; several code bases, several development schedules, several under-resourced development teams. And there will be more than one set of managers involved, trying to cover themselves against criticism, and finding reasons to blame the other guys. A solution is to make it explicit and obvious that the contract will change; give it a version number, advertise a schedule of monthly or quarterly changes in the contract doco/comments, and make some changes. A necessary part of the solution is to make sure that all involved - including managers and business analysts - understand (1) what a web service is (dont laugh - I've explained to senior BAs twice in the last 6 months), and (2) they're flexible.
  18. Not designing WSDL before your code does not mean you're not using contract-first methodology. If you have a well designed domain model, your application service interfaces are the contract and simply exposing them as SOAP web services does not mean that you're coding first. How do you design contract first in a non-SOA application, design your interfaces. I think we need to make our code and language constructs the first class citizen. To me, SOAP/WSDL is just an interoperability technology. You might also want your interfaces exposed as REST, RMI, etc... Exposing your (interfaces) as some transport technology has nothing to do with whether you're following contract-first practices. Ilya
  19. Not designing WSDL before your code does not mean you're not using contract-first methodology. If you have a well designed domain model, your application service interfaces are the contract and simply exposing them as SOAP web services does not mean that you're coding first. How do you design contract first in a non-SOA application, design your interfaces.

    I think we need to make our code and language constructs the first class citizen. To me, SOAP/WSDL is just an interoperability technology. You might also want your interfaces exposed as REST, RMI, etc... Exposing your (interfaces) as some transport technology has nothing to do with whether you're following contract-first practices.

    Ilya
    Michi Henning/Steve Vinoski: "Advanced CORBA Programming with C++" Even if you can find people that think only SOA/WebServices are the only implementation-language-independent-enabling -paradigms/technologies. Anyway, I am happy to see that there are still people with a thinking head. Guido.
  20. I agree with you, SOAP/WSDL is just an interoperability technology, and it's not mandatory to define the contract of your service as a WSDL file. But when you do create a SOAP frontend of your service, you should begin by designing the WSDL, with whichever method you use. That's coming from experience dealing with various SOAP toolkits. But as you say, the WSDL is not the alpha and omega of your service, it's just one of its frontends. I often hear people saying they don't want to use contract first because they don't like WSDL... If you don't like WSDL, don't use SOAP, but even if you don't use WSDL and SOAP, you have to think about your contract.