Fortresses, Documentation and Other tidbits
A wild argument on documentation has been going on by Oren here, then by Frans here and Oren's reply.
As I tend to agree with Ayende, I do find that doing documentation does help me organize myself some times. Don't get me wrong here. I'm not some documentation-crazy maniac that writes thousands of pages of documents every day. I am a coder! That's what I like to do. The thrill of creating a new beast out of nowhere is hard to achieve in several other areas of my life (except my family which is on top of all things).
So most of the time I get an idea (which at the time seems the most amazing thing since hot water) and just get to go build it.
The thing is I may not be as good a developer as I like to think, but several times I tend to undertest the code I write. Not that I don't TDD (may the Coding God not hear me), I do. It's just that I don't really take the time to think of a comprehensive enough list of tests to write for my code. Hey, if my test passes, it does work, and as someone who doesn't code *just* for a living, that lives to code, I know that this just ain't right.
Then at the end of the iteration I run my hateful friends: Code Coverage, Code Analysis and Dependency Analysis. And they kick my butt! Of course each time I correct a failure, I learn, so the next one is less flawed. Still there's an awful LOT of time involved in polishing my code.
So you're thinking: "Well, is this moron gonna say something or what?". I am! If you read my last post you know how much I do love the security implementation that MS did for Asp.Net (my coworkers are starting to call it MortSoftware or MicroMort, but I don't find appropriate to do it to the company that supports me and my family!). So I did what any good developer would do. I just thought: "well I''l just build it myself then!".
Well from this the Digital Fortress project was born. At some time I REALLY gotta organize all my projects into one comprehensive spot, since there are probably 8 projects going on right now. Well, at first I thought: "Hey how hard can it be to build an authentication/authorization framework? Piece of cake!". Talk about famous last words! The problem is a lot more complex than I first thought it to be, since I decided on taking the more sophisticated approach (Service-Oriented with WCF so you can configure your service to run your own way).
This is where I wanted to get. There are some times that documentation DOES matter. For the following reasons:
- Transparency - If I want people to use a piece of software that's so critical as a security suite, I want it to be an informed decision, so I want to give as much information as possible.
- Quality - If I want people to take my word on the information I provided, well I gotta do the logical thing: PROVE IT! So I decided on coming up with the test suites BEFORE writing the application.
- Brainstorm - As I write the documentation I get to think about what I'm writing, instead of writing it just to see that I took a bad turn. I'm not saying anything against Proofs-of-concept. I'm talking about just writing to see what happens (I do that a lot too hehehe).
- Peer Revision - The documentation I write is reviewed by the guy working with me in the project, and I review his part of it, so we do find several things amiss, discuss it and come with a better solution to the issue. Several things I've never seen before.
I do believe that people didn't understand what Oren had to say, or I didn't, because I don't see him being against all kinds of documentation. What I did understand is that he'd take quality, well built code with poor docs than crappy code with extensive documentation. I WOULD TOO!
This is why I'm proposing on-demand documentation. I'm experimenting with it. I'm not saying that it will resolve poverty around the world. Just something to toy with. I'm writing the operations that my agents (helpers to WCF services) will need to implement, as well as ALL the tests that need to be performed to consider that operation implemented.
I learned that in a couple hours I had defined almost all methods for the Digital Fortress agents and all test suites (obviously the list will grow and that's good). But the key point here is not the documentation that we built! It's all about all the nice ideas we had on the process of writing it, and all the mistakes that we avoided making just by thinking ahead. I'm sure there are you guys out there that think chess-like and see several moves ahead, but I like to give my brain a little break sometimes.
If you'd like to learn more about the documentation I'm toying with, please help me develop the concept further at the Digital Fortress discussion forums or at the Vision Statement pages as comments.
#108