Posts Tagged ‘documentation’
It is, at least in MSSqlserver, possible to annotate fields. Please do.
There are people coming after you to maintain the code base. One day it might be you who come after someone. Start paying it forward.
The field explanation might be in the Documentation but the Documentation is too often faulty, not accessible and almost always not up to date. The database is closer and probably easer to keep in sync with reality.
Don’t think a field name is self explanatory. The field CustomerID in table Customer might be. But the same field in Region is not. Is it the region master or the primary customer or what? By the time the field was created the meaning of this field was clear but not a year afterwards.
The reason I write this is that I presently work in a project where the habile predecessor has written down the meaning of the fields and saved me lots of time and lots more of confidence of what the figures mean and tons of debugging time.
Correction; Considered a warning.
Here is a good rule-of-thumb: If you have to write an SQL with Select Distinct, do adjust your chair, get a cup of coffee, walk around the office but above all talk to someone else because Select Distinct is a symptom of something being wrong, either in the database or in your solution.
/* Select Distinct is normally not needed when your database is lagom normalized. But if you do need a Select Distinct then this is a very good example of a situation that needs to be documented.*/
I found a blog entry at http://www.matshelander.com/wordpress/?p=74 which although lengthy and wordy hits the spot. There is no good notation system for software architecting.
My words: Comparing software architecting to building houses is ridiculous. Just because they share the same name (architecting) doesn’t mean they have a lot in common. Compare a sea horse and a horse and you get the same useless result.
The romans would never be good at mathematics since they lacked a good notation.
What software architecting needs is a good notation. UML is one way but it is not very good for evolving solutions and finding bugs. Code is the best notation I know of but it is too close to the very program and not good at describing architecture.
Besides, after several thousand years of building houses we still miss the estimated cost.
With no information you have one task.
1) deduce the right information
With the wrong information you have to:
1) understand the information
2) find out that the information is wring
3) deduce the new information