I wrote this, to turn my frustrations about the state of NoSQL documentation into something positive. I didn't think it'd get HN'ed so quickly. I look forward to suggestions for new gospel.
I find the "commandments" format to irk me slightly. I realise it lends a ready-made structure to any document, but "thou shalt" is sufficiently fusty that it can rub people the wrong way.
I've found the pattern format to work well in practice, because a well-written pattern pretty much explains itself. In particular, framing the discussion with a problem helps to illuminate when and where a pattern ought to be applied.
In terms of your general thesis in #2-5 that formal specification has failed and that a structured form of informal specification (wrap your head around that one, fellow pedants) ... I'm not sure.
I mean some of what you've argued for seems to me to be a "language design smell" -- just as some of the original Go4 patterns were seen in retrospect to be. So for example when you argue for taking a contractual approach. Why shouldn't that be in the language? It's not as though you have to go all the way to writing Z specs or Coq proofs. Personally I'd be perfectly happy to step up to Eiffel contracts.
Guarantees embedded in source code also have the nice property that they are slighly less likely to turn out to be filthy horrid lies; just as is generally thought of sourcecode comments.
I agreed with point 7, about stating the end state of the method rather than its process. I feel the same way about tests; I find test doubles to be thoroughly unsettling because I wind up explaining the logic of my program twice, instead of separating mechanism and validation. Perhaps such "naked mechanism" is just another indicator of code that will require high coupling.
Where you went wrong was that you, like I, assume that things with "database" on the label have silly-old fashioned notions like a fanatical focus on data safety.
I also agreed strongly with 8 and 9. Sometimes I look at the front page of HN and it is totally unintelligible gibberish. Having to know the intricate injokey history of two dozen sequential puns to run a piece of software drives me up the flaming wall. It's one of the things I least like about the ruby ecosystem.
Your claim that "Chances are, if you're reading this, you already are a disciple" turned out to be true for me. Good job. I think everyone knows good and bad documentation when they see it, but breaking it down into actionable rules like this is great.
If I could add something, it would be that there are both local and global assumptions, and both need to be specified. There are rules like "this input array must be sorted" and there are rules like these: http://blogs.msdn.com/b/oldnewthing/archive/2006/03/20/55551... (yes, it's bad that this is a blog post and not documented officially anywhere AFAIK). For example, sometimes it's surprisingly hard to find out that the developers of some library you're using assumed that callbacks never throw exceptions, even though it seems to work almost every time.
Interesting. There are certainly different kinds of assumptions and invariants. I like the idea of separating them by local vs. global scope; the latter are underdocumented.
Much as I like, say, the javadoc format, it channels devs into "function by function" thinking and documentation, and global assumptions and global invariants, typically do not get treated adequately.
A bit of time making this more concise and cleaning up the language would go a long way when you get the time. Clarity above all other virtues for documentation, goes doubly for meta-documentation.
Treating docs like specifications may seem onerous because of the specs that come to mind: entire languages, or the CSS/HTML specs. Massive documents, way too much work.
And, yeah, it's a big spec. But CL is a big language, and not just any language, but a batteries-mostly-included language, fully specified.
In contrast, the programmer-facing API for most libraries is going to be fairly small. HyperSpec-quality docs probably wouldn't be that hard for most small-to-midsized projects.
If you're wondering how to write thorough doc for an engineering audience, I highly recommend looking at IBM's doc for z/OS. The first thing you'll notice is: there's a lot of it.
Readit News
I've found the pattern format to work well in practice, because a well-written pattern pretty much explains itself. In particular, framing the discussion with a problem helps to illuminate when and where a pattern ought to be applied.
In terms of your general thesis in #2-5 that formal specification has failed and that a structured form of informal specification (wrap your head around that one, fellow pedants) ... I'm not sure.
I mean some of what you've argued for seems to me to be a "language design smell" -- just as some of the original Go4 patterns were seen in retrospect to be. So for example when you argue for taking a contractual approach. Why shouldn't that be in the language? It's not as though you have to go all the way to writing Z specs or Coq proofs. Personally I'd be perfectly happy to step up to Eiffel contracts.
Guarantees embedded in source code also have the nice property that they are slighly less likely to turn out to be filthy horrid lies; just as is generally thought of sourcecode comments.
I agreed with point 7, about stating the end state of the method rather than its process. I feel the same way about tests; I find test doubles to be thoroughly unsettling because I wind up explaining the logic of my program twice, instead of separating mechanism and validation. Perhaps such "naked mechanism" is just another indicator of code that will require high coupling.
Where you went wrong was that you, like I, assume that things with "database" on the label have silly-old fashioned notions like a fanatical focus on data safety.
I also agreed strongly with 8 and 9. Sometimes I look at the front page of HN and it is totally unintelligible gibberish. Having to know the intricate injokey history of two dozen sequential puns to run a piece of software drives me up the flaming wall. It's one of the things I least like about the ruby ecosystem.
Particularly when used inconsistently, e.g.: Thou shalt specify your assumptions
If I could add something, it would be that there are both local and global assumptions, and both need to be specified. There are rules like "this input array must be sorted" and there are rules like these: http://blogs.msdn.com/b/oldnewthing/archive/2006/03/20/55551... (yes, it's bad that this is a blog post and not documented officially anywhere AFAIK). For example, sometimes it's surprisingly hard to find out that the developers of some library you're using assumed that callbacks never throw exceptions, even though it seems to work almost every time.
Much as I like, say, the javadoc format, it channels devs into "function by function" thinking and documentation, and global assumptions and global invariants, typically do not get treated adequately.
But I fell in love with the CL HyperSpec years ago. Pick any section, (http://www.lispworks.com/documentation/HyperSpec/Front/) ... and it's amazingly clear, with sample code and everything.
And, yeah, it's a big spec. But CL is a big language, and not just any language, but a batteries-mostly-included language, fully specified.
In contrast, the programmer-facing API for most libraries is going to be fairly small. HyperSpec-quality docs probably wouldn't be that hard for most small-to-midsized projects.