3 ms·
jashkenas touches on it, but here's my rule of thumb for doctests: Test your documentation, but tests aren't documentation. In other words, it's great practic
by bryanlarsen 14y ago
jashkenas touches on it, but here's my rule of thumb for doctests:
Test your documentation, but tests aren't documentation.
In other words, it's great practice to ensure that code snippets inside your documentation execute correctly. Your primary benefit is that your documentation is correct, complete and up to date. Any testing benefit is purely secondary; you need a complete test suite regardless. You can use a doctest framework to create this test suite for convenience, but recognize that your doctests are going to be either illustrative or complete, but cannot be both.
Examples:
Here's a tutorial written in git comments so that each step is fully executable: http://cookbook.hobocentral.net/tutorials/agility http://cookbook.hobocentral.net/tutorials/agility
Here's a manual page written in rubydoctest: http://cookbook.hobocentral.net/manual/scopes http://cookbook.hobocentral.net/manual/scopes