Nearly everytime when talking about commenting interfaces or source code, the question "why documentation?" is raised. I realized that there are a lot of different motivations for writing some comments in natural language. My personal one is that I use writing in natural language as a tool to reflect my own thoughts. If I am not able to explain or formulate something, this might indicate that my solution is not ready right now.
So why should I write a contract for an operations? In this posting I try to collect some reasons for writing a contract. Here is my current list:
- Reflect my own work or thoughts
- Specify a task (for another person)
- Get juristic safety when providing software-operation to another, external organization (e.g. another company).
- Define what an operation should do (e.g. for later maintenance: its easier to decide if the implemented operation does things correctly)
- Agree with somebody else on an operation and work in parallel on it (more precise as only with code)
- To be continued ...
Feel free to post your reasons with a comment :). I am very excited to read them.
The lawyer Troy Sutton deals with this question in a more general juristic context in his article "Construction Industry Documentation and Record Keeping". This article doesn't focus only on system, but also project documentation. I personally think that it depends strongly on the organizational contexts of the contractors if this huge effort is really necessary.
AntwortenLöschen