+972 52-548-6969
Kobe – When the documentation is the only delivery that matters
When comparing the Kobe code base to the Kobe documentation, I am starting to get a sinking feeling. The documentation is really nice, the code is anything but.
When you put out guidance, the documentation is nice, but it is the code that people are going to look it, learn and try to emulate. And when you put out something that doesn’t meet basic parameters for good software, that is a huge problem.
With Oxite, Microsoft had the excuse of it being slipped out without anyone noticing. This time it is official, it has passed the proper review procedure, and is explicitly marketed as “intended to guide you with the planning, architecting, and implementing of Web 2.0 applications and services.”
Sorry, that is entirely unacceptable.
Putting something like that out there as guidance is actively doing harm to the community as a whole. It means that people who would look at that and try to use what they see there are going to get bitten by bad practices, bad architecture and overly complex and redundant approaches.
Phil Haack said that: “I was part of a high-level review and I felt most of the app that I saw was reasonably put together.”
I submit that high level review of such guidance packages is absolutely not sufficient. You have to get people to do a full review cycle of that, which include the code, the documentation, the reasoning and anything else that is going out there.
Comments
What exactly is a "high-level review"? A discussion on the documentation? A look at the general design of the application, maybe in some form of UML or other design language? I can't imagine it's the latter - any repository interface that has something like 60 functions should automatically send up a warning signal. Hell, any interface at all that has 60 functions ought to cause the person who wrote it to be fired.
I'm gonna guess haack's high level review meant looking at the documentation and some developer overview of the app concepts without much discussion of the code.
I wrote a follow-up comment to my post that talks about this a bit and asks the question of how we can make it better.
haacked.com/.../code-sample-taxonomy.aspx
The review was informal. They showed us some slides of the high-level architecture. They told me about their data access and they were using the Repository pattern.
Then we looked at an action, a view, etc... Some of it was clean, some of it wasn't. I gave them some feedback, and we went our merry ways.
What I didn't do was go through a line-by-line code review, nor did I explore the source. Obviously now, I wish I had. But at the time, I was pressed for time and their questions were really focused on how to do things the MVC way. I warned them about Oxite, which they were aware of, and went on my way.
If you don't mind, please comment on my post if you have suggestions how we should handle this better in the future.
Comment preview