Shawn Walker wrote: > > Attention and resources are finite, and it is not reasonable to expect > all interfaces to be documented to any specific degree.
Some minimal level of documentation, really does not take that long. The issue is more that, "most engineers dont WANT to write documentation". This is a bad attitude, especially if they are getting PAID to write code. > The documentation of "private" -- indicating that others should not > use this function, and if they do, do so at their own risk, is the > best option imo. > > I also feel that your argument is no longer as strong as it once was > given that almost all the source code for Solaris is now available. > Thus, individuals that wish to use things that they were not intended > to use can do so if they really want to. As someone else recently pointed out, "having access to the source", is not at all the same thing as having a little documentation about it. Having documentation, can make all the difference to a volunteer coder, between "I think I'll try to do something here", vs "ugh, I think i'll just do something else". Having the original engineer spend 5 minutes on documentation, can save some later person looking at the code, 5 *days*. That later person, may have an interest in doing something "innovative" with the code. However, ... finding someone with sufficient motivation to do something, even WITH documentation, is challenging. Finding someone with sufficient motivation to spend DAYS reverse-engineering something that should have been documented in the first place... is near-impossible. The feelings that come about are; "These people couldnt spend 5 minutes to write a little documentation to clarify this jumble. If they dont care enough to spend 5 minutes writing a little doc, why the hell should I care to spend my time on it?!"
