<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">
<br>
<div>
<div>On Aug 24, 2011, at 12:02 PM, Soren Hansen wrote:</div>
<br class="Apple-interchange-newline">
<blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; ">2011/8/24
Jorge Williams <<a href="mailto:jorge.williams@rackspace.com">jorge.williams@rackspace.com</a>>:<br>
<blockquote type="cite">
<blockquote type="cite">Let me start by saying that I have no idea why we're having this<br>
</blockquote>
</blockquote>
<blockquote type="cite">
<blockquote type="cite">discussion again. We talked about it at the design summit and we<br>
</blockquote>
</blockquote>
<blockquote type="cite">
<blockquote type="cite">agreed we'd move forward in pretty much exactly the way Vish describes<br>
</blockquote>
</blockquote>
<blockquote type="cite">
<blockquote type="cite">it.<br>
</blockquote>
</blockquote>
<blockquote type="cite">I believe I attended all discussions on the compute API. We agreed<br>
</blockquote>
<blockquote type="cite">to design the spec in a more open and agile manner -- I'm all for<br>
</blockquote>
<blockquote type="cite">that. I don't remember ever discussing generating the spec from code.<br>
</blockquote>
<br>
Generating the spec from code (or docstrings living in code, rather) was<br>
informally discussed in San Antonio in November.<br>
<br>
<blockquote type="cite">I also don't remember ever discussing where the spec will live. Not<br>
</blockquote>
<blockquote type="cite">that I really care where it lives, I just don't remember talking about<br>
</blockquote>
<blockquote type="cite">it.<br>
</blockquote>
<br>
This was the subject for an entire session in Santa Clara. Making code<br>
and docuemtation live together to ensure they'd be in sync at all times.</span></blockquote>
</div>
<br>
<div><br>
</div>
<div>Okay, I do remember these, but the talks focus on documenting what the implementation does. I'm all for it, docstrings are good, but that's not what I usually think of a specification. So we are having a semantic disconnect here....</div>
<div><br>
</div>
<div>
<blockquote type="cite">OpenStack was created to stop every company wanting to do offer cloud<br>
computing from reinventing everything and have everyone work together.<br>
What's the use of competing implementations? We'll be right back to square one.</blockquote>
<br>
</div>
<div>Because whether you like it or not there are competing vendors... and each wants to add it's special sauce in order to remain competitive. Also, because companies that have existing products may find it easier to add an OpenStack compatibility layer rather
then switching to our implementation -- at least in the short term. (As long as they use our API we still win from this.) And finally, because it's hard to write an implementation that's all things to all people. Other implementations may want to specialize
in one manner or another.</div>
<div><br>
</div>
<div>I've been doing some research to try to understand the disconnect that we are having. For example, the idea of multiple implementations and the separation of spec from implementation seems quite natural to me, but is obviously alien to others. I've
found a great blog post that illustrates the difference, and states that it seems to stem from the fact that there are cultural differences between coding languages. Note the blog is from PJ Eby, the author of PEP 333. Worth a read:</div>
<div><br>
</div>
<div><a href="http://dirtsimple.org/2004/12/java-is-not-python-either.html">http://dirtsimple.org/2004/12/java-is-not-python-either.html</a></div>
<div><br>
</div>
<div><br>
</div>
<div>
<blockquote type="cite">Like, say, having the<br>
spec be generated from docstrings in the code and at the same time run<br>
tests based on the contents of the docstrings to ensure that what the<br>
docstrings says the API will accept and return is also what it actually<br>
accepts.</blockquote>
</div>
<div><br>
</div>
<div><br>
</div>
<div>I like this approach to testing because the docstrings aren't generated from what the code does, they are written by hand. This is a good approach for confirming that the impl meets up with the spec. I'm not so sure that there would be enough there to
document things in enough detail though to form as the basis of the spec.</div>
<div><br>
</div>
<div><br>
</div>
<div>-jOrGe W.</div>
<div><br>
</div>
<font face="monospace">This email may include confidential information. If you received it in error, please delete it.</font></body>
</html>