Let's go off on a tangent here as this is one of the reasons people find it so hard to implement specs and standards. What is the correct HTML standard? The answer really is whatever reference renderer you use. Remember again that to fully specify the HTML standard, it would have to be long and detailed enough to essentially be source code. A small example I just recently ran into is Read-only text boxes. Firefox renders it the way I like. A read only text-box is 'greyed out'. In IE, it looks the same as a writable text box. Not being a web-programmer, this was news to me. I suddenly feel old and outdated as I am sure many of you are thinking that is so 1999. The HTML specification of course says nothing of the 'right' way to do this. This is natural of course as to get the HTML to render the exact same the specification would be so long detailing colors, border widths, bevels, how round corners should be, gradients... I'd hate to be in that committee.
These days, it seems WebKit is becoming one of the 'standard' renderers. You must behave as WebKit behaves. So why not use Webkit directly? Hence, we see many more browsers moving towards it rather than playing a game of constant catchup. Have a look at the alternative if you wish. Microsoft has released many specifications of its formats. They are insanely long and I doubt they are fully specified. I'd be more than willing to wager that to actually implement any of their standards, you would have to launch their renderer (MS Word), see how it renders something, and then copy it. I do not fault Microsoft here. It's just the reality of writing specifications. Having worked in the networking field, we did this all the time. Some part of the specification is vague or strangely worded or missing. What do we do? We hook it up to the 'standard' Cisco box and see how it behaves. Then we make sure we behave the same way. Sometimes you are lucky in that as more and more people do this, the 'specification' is updated to include all the little vagaries people ran into along the way. We're actually quite fortunate in networking as the protocols themselves are fairly straight forward and they rarely change. Case in point is IPV4. Despite all the problems with it, it is still the dominant protocol. Contrast that in other fields where change flows much quicker.
Granted, often times companies don't want to just give you the source code as they spent time and money developing it. They might want your software to be incompatible, so that they can claim your software is broken and less reliable than theirs. One of the beauties of open source is that you don't need to read the specification. You can just link the source directly.
My only point here is to suggest that to FULLY specify something, the actual source code is often the most concise and best method of doing it.
I believe the solution to this problem lies in changing attitudes. First and foremost we need to change the language used by us and the academic world. I never want to see the phrase 'design and implementation' ever mentioned again. Can we make me the word czar of the United States? Even if 'we' understand the academic difference that the design can be conceived independent of programming language, when this reaches the wider management and business community, it is reduced to the very problem discussed here. We should only speak of high level and low-level design.
Next, we need to recognize the validity of source code itself as a valid specification. That is exactly what it is. You don't see civil engineers trying to write an essay to describe a bridge when an auto-cad blueprint is the real design. We need to treat our source code as the specification that it is. That means writing it neatly and cleanly. Putting separate objects in separate files. Just as the civil engineer doesn't scribble over his designs, neither should we leave our source code mangled with undecipherable variable names. You should be able to read it with ease. I suggest we as software engineers bare a great deal of responsibility here. Often times our source code resembles a blue print with eraser marks, numbers scratched out, pages duct tapes together, big arrows leading to other documents and a big TODO that leaves out critical functionality... We should also try and use programming languages that make being a valid specification easy. C# for example has the ability to have a lot of meta information and attributes within the source code itself. I hope this process continues and is expanded in more languages. The more expressive the language, the more we can offload onto the perfect compiler.
We should use valid design documents were possible. It should aid in the source code specification, but should not be the specification itself as that is not what the implementers (compilers) use to produce the final result. Putting emphasis on useful design documents will allow for more man hours to be spent here instead of on useless items. I tire of seeing someone copying the header file of a c++ class, pasting it into a word document and claiming that is valid documentation. Designing GUI prototypes, timing diagrams for network protocols, class and interface maps, overall design choices... are all essential in guiding the source code.
Last, but not least is something I haven't touched on too much, but it is implied. Software is not trivial work. As such getting good people and training them is essential. You cannot separate the specification or design or knowledge from the code. The latest fad is something called a 'subject matter expert (SME)'. I say this is a fad as it assumes that you can separate the person doing the coding from the person that 'knows stuff.' In the networking world, this is the person that knows the protocols and specifications down to a tee. No worries though. They don't program. That is just the trivial matter left to the mundane implementers. I had such an experience recently at a company I worked for. They had a PHD who was supposed to be a subject matter expert. Of course there were the programmers actually writing the code, debugging issues, working on interoperability, coding which bits need to be set, what values go in what fields, and so on. The programmers ended up having to know more about the specification than the SME himself. Do I really need to rewrite the article on the futility of separating the SME from the programmer? In the end, it is your programmer who will debug issues, solve problems... They need to be experts in the subject matter. I suppose you could have an SME who does not code. It's just that the programmer would have to bother them for every line of code. In the end, the SME would probably be better off just writing the code themselves.
If you are hesitant to make the leap of realizing that to fully specify something, you essentially need to code it or that a programmer needs to be a subject matter expert... let me summarize this article with an old philosophical question.
Can you have thought without language?
Some of best languages we have found to precisely specify many routines are the programming languages. No other written language offers as much clarity or conciseness as a modern programming language.
About the Author
Yamin Bismilla is a graduate of the University of Waterloo's Computer Engineering program and is currently a software developer in the Toronto, Canada Area.