5 ms·
Margin Notes: Automatic code documentation with recorded examples from runtime
- chewxy 8y agoSlightly related are Go examples - they're tests, and documentation at the same time. It'd be nice if someone hooks in a listener to automatically collect examples tho
- pmontra 8y agoAnd Elixir's doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
- merlincorey 8y agoAnd Python's Axe! I mean doctest: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html
- westurner 8y ago1. sys.settrace() for {call, return, exception, c_call, c_return, and c_exception} 2. Serialize as/to doctests. Is there a good way to serialize Python objects as Python code? 3. Add doctests to callables' docstrings with AST Mutation testing tools may have already implemented serialization to doctests but IDK about docstring modification. ... MOSES is an evolutionary algorithm that mutates and simplifies a combo tree until it has built a function with less error for the given input/output pairs.
- gklitt 8y agoYeah, I like doctests but also find it limiting to have everything in the source code text. Having a GUI for viewing examples is nice, although it does introduce other problems like how to store and version the examples.
- weaksauce 8y agoThis is really neat. It would be awesome if something like this was added into the language server protocol so you could have it everywhere and standardized.
- gklitt 8y agoYeah, the examples are serialized so it's theoretically possible example recorders in any language that emit a standard format. It's kind of just a logging format in some sense. On the viewer side I've thought about building a Sourcegraph extension which would consume a standardized trace format and then display it in any editor, on Github, etc.
- jmiserez 8y agoVery cool. One could do this over time, and then automatically find out where values change between different versions of the code. Might be able to find bugs before they ever occur.
- wtroughton 8y agoI'm surprised that there isn't more adoption of tools like this to help developers understand code. Even for statically typed languages like Java, I find the existing tools lacking in helping me understand the code thoroughly. I mostly rely on the IDE to navigate code which I then mentally jot down the behavior of the code segment. Writing code this way is way too error-prone, and unfortunately testing isn't foolproof either. It isn't until something breaks that we really begin to learn the nuances of the system...
- drudru11 8y agoNicely done - excellent presentation. I hope this becomes a thing in Visual Studio Code.