DEV Community

Discussion on: Self Documenting code isn't

Collapse
 
notriddle profile image
Michael "notriddle" Howell • Edited

Anything with doctests. Unai Esteibar listed Elixir's exunit, and this is also a feature of Rust's rustdoc, and there are less-official ways to add it to other languages.

Like all automated testing systems, though, it's only a partial solution. The best comments I've ever seen tend to be things like this:

From a user's point of view, realm_view_pills_button looks exactly the same as realm_view_pills, and should never have any user-visible differences.

The reason we have both is that realm_view_pills_button is actually a bunch of buttons under the hood, and will completely rebuild the view and hit the network when you switch tab. You should use it if you expect more than five tabs. realm_view_pills, on the other hand, is actually a Bootstrap pills-tabs view under the hood, and allows the user to switch between them more quickly.

You try writing that kind of stuff in a way that gets automatically checked.