It is true that debugging[1] options are not well documented, however it is also true that they are intended for use only in exceptional cases or by V8 developers. Many of them are not even available in release build of V8 that is shipping with Chrome (like disassembler or ability to trace IC transitions, which is a shame).
I would say that I am a bit torn on this issue.
First of all, I would love anybody using V8 to be able to troubleshoot issues they are running to as easily as possible. Ideally you should see your source annotated with optimization suggestions and internal V8 information translated into digestible form. I experimented with some ways of doing that but sadly I totally lack time to make a product out of that.
However I am not sure making some static cookbook of performance patterns is the right way to go here. It certainly can help in the short run, but in the long run its the uniformity of optimizations on V8 side and general shape of your code that matters. I fear cargo cult blindly following such a cook book without making an attempt to understand.
Additionally I fear that it is extremely hard to make and maintain such a cook book given that VMs consist of extremely many moving components and sometimes you can't decompose performance of an application into performance of small patterns, they interfere with each other. Understanding of internals, or understanding of how and where get the information on internals is much more important.
Maybe I am wrong, but I am doing my best to actually help people to become interested in V8 internals instead of following blindly recommendations.
[1] note: we are not talking about JavaScript debugger itself which should be relatively well documented as far as I understand, C++ header files look like they contain a lot of comments and I know there is a protocol description on the wiki.
I definitely agree with you on the reasons why concrete performance rules/documentation is dangerous - I historically have tried to advocate for better introspection/debugging tools instead of just lists/documents. But so far the reaction to those has been pretty cold; it seems as if most engine devs I speak to view introspection tools/APIs as equivalent to documenting (and thus locking in) internals and runtime design details. I can understand how shipping a product like this as a part of a large software org is pretty hard - it's difficult to establish how many customers it has and what the benefits will be.
Not really sure how we get out of the spot we're in, unfortunately - in practice JS optimization is a mix of black magic and cargo cult wisdom that can become outdated as engines improve, and I can see that causing a lot of long term drag on productivity as engine authors have to keep tuning their engines for bad code.
I hope you keep getting traction on exposing developers to V8 internals; the stuff I've learned about both V8 and spidermonkey internals has been very useful so far - my complaint is largely that the learning process is difficult, not that there's anything wrong with your codebase :) I love that so many of the v8 JS builtins are self-hosted in JS instead of C++ - makes it much easier to peek under the hood and figure out what they're doing!
I would say that I am a bit torn on this issue.
First of all, I would love anybody using V8 to be able to troubleshoot issues they are running to as easily as possible. Ideally you should see your source annotated with optimization suggestions and internal V8 information translated into digestible form. I experimented with some ways of doing that but sadly I totally lack time to make a product out of that.
However I am not sure making some static cookbook of performance patterns is the right way to go here. It certainly can help in the short run, but in the long run its the uniformity of optimizations on V8 side and general shape of your code that matters. I fear cargo cult blindly following such a cook book without making an attempt to understand.
Additionally I fear that it is extremely hard to make and maintain such a cook book given that VMs consist of extremely many moving components and sometimes you can't decompose performance of an application into performance of small patterns, they interfere with each other. Understanding of internals, or understanding of how and where get the information on internals is much more important.
Maybe I am wrong, but I am doing my best to actually help people to become interested in V8 internals instead of following blindly recommendations.
[1] note: we are not talking about JavaScript debugger itself which should be relatively well documented as far as I understand, C++ header files look like they contain a lot of comments and I know there is a protocol description on the wiki.