4 ms·

Elixir also has this feature called doctests[0]. That said, rust documentation is also really good. [0] - https://elixir-lang.org/getting-started/mix-otp/docs-

Elixir also has this feature called doctests[0]. That said, rust documentation is also really good. [0] - https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...

hangtwenty 6y ago
I am so glad to learn about these features in Rust and Elixir. I'm coming from Python originally, so I always want them! https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html https://docs.pytest.org/en/stable/doctest.html https://docs.pytest.org/en/stable/doctest.html
- mcintyre1994 6y ago
  I had no idea that Python had a library for this, nice! Skimming that doc, it's especially impressive how well it looks to handle exception tracebacks.
masklinn 6y ago
I mean doctests are not exactly new. The `doctest` module was added to Python in 2.1, back in 2001. And even that is largely just a weak shade of semi-literate programming, to say nothing of actual literate programming.
- steveklabnik 6y ago
  This is one of the things I really love about Rust, and also one of the things that's most challenging for its adoption. Not a ton of stuff in Rust is new, but it does present a new mix of old things, and often, those things are new to many people, even if they're actually old.
  - est31 6y ago
    Rust took out the things considered best practice and provided them to users by default, or checked for them by default. This includes simple things as explicit names for types like u8 instead of char (as you are going to assume the size of char anyway, let's be honest... most code won't work on 16 bit char platforms). But it also includes stuff like unifying naming conventions, or providing a good package manager. C++ has multiple package managers, as does js. But rust had a great one from the start and for now there doesnt seem to be the need for people to use alternatives, because nobody had to come up with them. So no balkanization of standards and the costs for users that this entails. Maybe with age this will change, but for now Rust is doing quite well.
- sitkack 6y ago
  I had to suffer with coworkers that would write doctests, bad docs and bad tests together at last! The solution here is to write real tests and hyperlink them in a marked up form to the functions they actually test. Coding inside of a doc string is an epic troll. This is a warning to anyone getting seduced by doctests, stay away! They invert the problem, when one should just write tests, it is a problem with the documentation and code discovery tools that makes this seem like a good idea.
  - steveklabnik 6y ago
    What is the distinction between a "real" test and a doc test that you're making? At least in Rust, they are the same thing.
    - masklinn 6y ago
      I'd guess their coworkers decided to write all tests as doctests, rather than use doctests to ensure examples run fine? Python's doctests are also formatted and in some ways behaving like an interactive shell session, with >>> code here output here rather than just "literate code" so the execution context is a bit strange. This makes complicated doctests hard to inspect and debug. Doubly so because there's almost no tooling which understands doctests. And of course on the flip side the best tests make for absolutely terrible examples since they try to exercise weird corner cases.
      - sitkack 6y ago
        Yes, this. I don't disagree in theory, I disagree in practice.
    - jedbrown 6y ago
      I think it's between a test written inside a comment (where smart IDE features don't apply) versus `#[test]` in normal code, where you have a rich editing environment and instant feedback (including `cargo build` failing immediately on errors). Perhaps it's just my perception, but doctests (in comments) seem slower to run.

hangtwenty 6y ago

I am so glad to learn about these features in Rust and Elixir. I'm coming from Python originally, so I always want them! https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html https://docs.pytest.org/en/stable/doctest.html https://docs.pytest.org/en/stable/doctest.html

mcintyre1994 6y ago
I had no idea that Python had a library for this, nice! Skimming that doc, it's especially impressive how well it looks to handle exception tracebacks.

masklinn 6y ago

I mean doctests are not exactly new. The `doctest` module was added to Python in 2.1, back in 2001. And even that is largely just a weak shade of semi-literate programming, to say nothing of actual literate programming.

steveklabnik 6y ago
This is one of the things I really love about Rust, and also one of the things that's most challenging for its adoption. Not a ton of stuff in Rust is new, but it does present a new mix of old things, and often, those things are new to many people, even if they're actually old.
- est31 6y ago
  Rust took out the things considered best practice and provided them to users by default, or checked for them by default. This includes simple things as explicit names for types like u8 instead of char (as you are going to assume the size of char anyway, let's be honest... most code won't work on 16 bit char platforms). But it also includes stuff like unifying naming conventions, or providing a good package manager. C++ has multiple package managers, as does js. But rust had a great one from the start and for now there doesnt seem to be the need for people to use alternatives, because nobody had to come up with them. So no balkanization of standards and the costs for users that this entails. Maybe with age this will change, but for now Rust is doing quite well.
sitkack 6y ago
I had to suffer with coworkers that would write doctests, bad docs and bad tests together at last! The solution here is to write real tests and hyperlink them in a marked up form to the functions they actually test. Coding inside of a doc string is an epic troll. This is a warning to anyone getting seduced by doctests, stay away! They invert the problem, when one should just write tests, it is a problem with the documentation and code discovery tools that makes this seem like a good idea.
- steveklabnik 6y ago
  What is the distinction between a "real" test and a doc test that you're making? At least in Rust, they are the same thing.
  - masklinn 6y ago
    I'd guess their coworkers decided to write all tests as doctests, rather than use doctests to ensure examples run fine? Python's doctests are also formatted and in some ways behaving like an interactive shell session, with >>> code here output here rather than just "literate code" so the execution context is a bit strange. This makes complicated doctests hard to inspect and debug. Doubly so because there's almost no tooling which understands doctests. And of course on the flip side the best tests make for absolutely terrible examples since they try to exercise weird corner cases.
    - sitkack 6y ago
      Yes, this. I don't disagree in theory, I disagree in practice.
  - jedbrown 6y ago
    I think it's between a test written inside a comment (where smart IDE features don't apply) versus `#[test]` in normal code, where you have a rich editing environment and instant feedback (including `cargo build` failing immediately on errors). Perhaps it's just my perception, but doctests (in comments) seem slower to run.