5 ms·

The problem with documenting internals is that it becomes a contract. Developers then start relying on those documented behaviors, and it later becomes much mor

The problem with documenting internals is that it becomes a contract. Developers then start relying on those documented behaviors, and it later becomes much more difficult to change them. It's bad enough as is with developers relying on undocumented behavior, see the troubles Wine (and Microsoft as well) with applications that touch Windows internals.

harlowja 13y ago
Isn't it the right thing to do though? Open source should not be about hiding behaviors behind undocumented code. Open source is about documenting it so that others can learn and jump in and help. It seems totally non-open if this is how V8 is developed.
- spiffytech 13y ago
  There is a distinction between documenting the portions of your app you intend people use, and effectively promising to maintain side effects and accidents of your existing design. mraleph says the public API is documented, which fulfills the obligation an open source project has. However, the discussion here is about side effects of the V8 implementation, as they relate to performance. That is to say, the V8 team is reluctant to do anything that suggests "if you write javascript using this pattern, your code will/will not run fast, but only because that's just how this week's code branch works out". If the team made those sorts of promises with a project as complex as V8, they effectively become locked in to their existing code, unable to change or improve much of anything because they'd be breaking the promises of performance patterns they previously issued. The authors who are working with V8, on the other hand, require those promises to be made. It's not enough for the performance patterns to be documented, these authors need them to be fairly stable as well. It's a tough situation - the V8 authors have made all the promises and documentation that's practical for them to do, but it's not enough to satisfy these other project authors' needs.
- chii 13y ago
  you confuse open source with extensible/flexibility/maintainability. Its open source if you have access to the source, not because you can grok the code. The internals of V8 ought to be undocumented, if it not intended to be an api that other systems interfaces with. Api behaviour should be documented, and i assume that's what the V8 team does - but the internal IR, for example, is private and its behaviour should not be relied up on, or do so at your own risk.
sgbeal 13y ago
The problem with NOT documenting PUBLIC APIs is that all behaviour becomes, from the client perspective, undefined. People keep going back to the point of private API docs - private details are private for a reason. Nobody but the v8 devs need private internal docs, and those MIGHT exist in encyclopedic form somewhere in Google. Those don't interest me. Public APIs are missing (or exceedingly poor, relative to v8's scope).

harlowja 13y ago

Isn't it the right thing to do though? Open source should not be about hiding behaviors behind undocumented code. Open source is about documenting it so that others can learn and jump in and help. It seems totally non-open if this is how V8 is developed.

spiffytech 13y ago
There is a distinction between documenting the portions of your app you intend people use, and effectively promising to maintain side effects and accidents of your existing design. mraleph says the public API is documented, which fulfills the obligation an open source project has. However, the discussion here is about side effects of the V8 implementation, as they relate to performance. That is to say, the V8 team is reluctant to do anything that suggests "if you write javascript using this pattern, your code will/will not run fast, but only because that's just how this week's code branch works out". If the team made those sorts of promises with a project as complex as V8, they effectively become locked in to their existing code, unable to change or improve much of anything because they'd be breaking the promises of performance patterns they previously issued. The authors who are working with V8, on the other hand, require those promises to be made. It's not enough for the performance patterns to be documented, these authors need them to be fairly stable as well. It's a tough situation - the V8 authors have made all the promises and documentation that's practical for them to do, but it's not enough to satisfy these other project authors' needs.
chii 13y ago
you confuse open source with extensible/flexibility/maintainability. Its open source if you have access to the source, not because you can grok the code. The internals of V8 ought to be undocumented, if it not intended to be an api that other systems interfaces with. Api behaviour should be documented, and i assume that's what the V8 team does - but the internal IR, for example, is private and its behaviour should not be relied up on, or do so at your own risk.

sgbeal 13y ago

The problem with NOT documenting PUBLIC APIs is that all behaviour becomes, from the client perspective, undefined. People keep going back to the point of private API docs - private details are private for a reason. Nobody but the v8 devs need private internal docs, and those MIGHT exist in encyclopedic form somewhere in Google. Those don't interest me. Public APIs are missing (or exceedingly poor, relative to v8's scope).