Re: [tlug] linux@example.com How many widely can we do that?

[Edward Middleton <emiddleton@example.com>]

Stephen J. Turnbull wrote:
> Curt Sampson writes:
>  > Stephen J. Turnbull wrote:
>  > > Even backward compatibility can be immediately disposed of as "we
>  > > changed unspecified behavior, you really shouldn't be depending on
>  > > that!" because *everything* is unspecified.
>  > 
>  > Well, only if you refuse to admit that your code is also a spec.
>
> Of course I admit it is *a* spec.  There is a place for reference
> implementations.  The problem is that if you have 1,000 revisions in
> your repo, you have 1,000 specs (or maybe a *lot* more if you consider
> the implied combinatorics of the patches).  Don't you think that is
> too many specs?
>   

Stephen, I take it your argument against inline documentation as the
spec, is that any change is immediately reflected in the spec so there
is no incentive to stick to a given spec.  In the projects I have most
experience with, this is less of an issue because most developers don't
like writing documentation so they only document fixed API's/behavour. 
If you look at rails as an example of inline documentation, the
documentation accounts for most of the bulk of the framework[1].  Inline
documentation might make it easier to change the spec, but there is
still the burden of re-documenting the change.  There is also the added
advantage that inconsistencies between spec and actual behavior become
more obvious.

Edward

1. http://www.loudthinking.com/posts/33-myth-4-rails-is-a-monolith