5 ms·

I just had an idea, but more in relation to documenting source code: what if there was a tool sort of like gofmt in that it has to be run in order for code to s

I just had an idea, but more in relation to documenting source code: what if there was a tool sort of like gofmt in that it has to be run in order for code to successfully compile, but instead of formatting, it actually checks if some or all of the variable names in functions or objects appear in some corresponding comment (like Python docstrings [0] or javadoc comments [1]). I just came up with the idea and the first (bad?) heuristic now, and I didn't check to see if tools with these characteristics already exist. It would be bad initially [2] and it would be onerous for sure, but it would be a start. [0] https://www.python.org/dev/peps/pep-0257/ https://www.python.org/dev/peps/pep-0257/ [1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html http://www.oracle.com/technetwork/java/javase/documentation/... [2] https://en.wikipedia.org/wiki/Colorless_green_ideas_sleep_furiously https://en.wikipedia.org/wiki/Colorless_green_ideas_sleep_fu...

steveklabnik 9y ago
In rustdoc, documentation examples are compiled and run whenever you run your tests. It's very helpful for this kind of thing. https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html https://doc.rust-lang.org/stable/rustdoc/documentation-tests...
- vog 9y ago
  Nice! Python has doctests which serve a similar purpose: https://docs.python.org/3.6/library/doctest.html https://docs.python.org/3.6/library/doctest.html
- slimsag 9y ago
  Just wanted to chime in and say that as a Go developer of almost 5 years now, running into Rusts' compiled examples has been quite cool. The cool thing about these is that you can actually (depending on the situation) make your examples your tests.
  - slrz 9y ago
    What makes them so different from godoc's examples?
- tareqak 9y ago
  Thanks for the example! To be completely clear, this is what I meant: Suppose this is the function we want to document (using examples modified documentation tests: fn foo { let x = 5; let y = 6; println!("{}", x + y); } Suppose we have a documentation requirement/heuristic of requiring the comment to have all the variables that are declared in the body of any given function. Then a comment like this would pass because whatever compilation step /processor sees that `x` and `y` both appear in the comment. // Prints x + y This would fail because `x` is not found: // Prints z + y This would pass but is not useful/misleading/wrong. // y - x FTW!!! This example is trivial and only uses the one simple heuristic such that it is both onerous and useless, but it would force the writer of the code to also write comments in accordance with said heuristic. In this particular case, if someone modifies the variable name, adds a new variable, or removes and existing once, then the compiler would force that individual to make a necessary change to that particular comment such that the comment cannot become stale (but the heuristic is bad, so it could still be useless :) ).
  - hamandcheese 9y ago
    I would argue that externally documenting declarations inside the function is not particularly helpful.
- twic 9y ago
  Python has something similar: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html For software with a command-line interface, perhaps it would be useful to do some testing at that interface, perhaps using BATS: https://github.com/sstephenson/bats https://github.com/sstephenson/bats That is also automatically tested, but describes the actual user interface.
ubernostrum 9y ago
In the Python world, about the best you can do is enforce the existence of API documentation. Most Python linters can check that every module/class/function/method has a docstring, though of course they can't enforce that it's up-to-date or useful to a human. Enforcing useful up-to-date documentation requires cultural setup work rather than technological setup work.

steveklabnik 9y ago

In rustdoc, documentation examples are compiled and run whenever you run your tests. It's very helpful for this kind of thing. https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html https://doc.rust-lang.org/stable/rustdoc/documentation-tests...

vog 9y ago
Nice! Python has doctests which serve a similar purpose: https://docs.python.org/3.6/library/doctest.html https://docs.python.org/3.6/library/doctest.html
slimsag 9y ago
Just wanted to chime in and say that as a Go developer of almost 5 years now, running into Rusts' compiled examples has been quite cool. The cool thing about these is that you can actually (depending on the situation) make your examples your tests.
- slrz 9y ago
  What makes them so different from godoc's examples?
tareqak 9y ago
Thanks for the example! To be completely clear, this is what I meant: Suppose this is the function we want to document (using examples modified documentation tests: fn foo { let x = 5; let y = 6; println!("{}", x + y); } Suppose we have a documentation requirement/heuristic of requiring the comment to have all the variables that are declared in the body of any given function. Then a comment like this would pass because whatever compilation step /processor sees that `x` and `y` both appear in the comment. // Prints x + y This would fail because `x` is not found: // Prints z + y This would pass but is not useful/misleading/wrong. // y - x FTW!!! This example is trivial and only uses the one simple heuristic such that it is both onerous and useless, but it would force the writer of the code to also write comments in accordance with said heuristic. In this particular case, if someone modifies the variable name, adds a new variable, or removes and existing once, then the compiler would force that individual to make a necessary change to that particular comment such that the comment cannot become stale (but the heuristic is bad, so it could still be useless :) ).
- hamandcheese 9y ago
  I would argue that externally documenting declarations inside the function is not particularly helpful.
twic 9y ago
Python has something similar: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html For software with a command-line interface, perhaps it would be useful to do some testing at that interface, perhaps using BATS: https://github.com/sstephenson/bats https://github.com/sstephenson/bats That is also automatically tested, but describes the actual user interface.

ubernostrum 9y ago

In the Python world, about the best you can do is enforce the existence of API documentation. Most Python linters can check that every module/class/function/method has a docstring, though of course they can't enforce that it's up-to-date or useful to a human. Enforcing useful up-to-date documentation requires cultural setup work rather than technological setup work.