So the big argument for making code "self-documenting" is that comments and documentation can get out of date (and lie) and code cannot. But obviously there is no silver bullet and everything you are saying is also very valid.
Are there any languages or environments that enforce commenting and documentation accuracy in some way? Like a compiler that demanded comments be structured a certain way and enforced that they be manually timestamped for correctness if the code they referenced changed? Obviously no system is perfect, but we rely on other pseudo-accurate measures of correctness like testing itself.
Really slick. Definitely seems like Elixir and Elm are two new languages going the extra mile to solve a lot of problems with functional programming while also making developers happy and sane.
In the Javascript realm, I think jsDoc is a must !
It's easy to write, help with auto-completion and "bad parameter" check. If your editor knows how to read it (and it should), it catch a lot of spelling mistakes.
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.
Clojure does not enforce, but you can comment what the function does like:
(defngive-me-motivation"Prints Rocky Balboa motivational phrase"[](println"Life's not about how hard of a hit you can give... it's about how many you can take, and still keep moving forward."))
As Michael noted and Unai exemplified with Elixir, there is this concept of doctests: code snippets with expected outputs to be inserted into documentation, executed and checked. I believe the first and most famous example is Python's doctest module, of which I'm a big fan :) and just got a nice post here in dev.to some days ago. I know there are third-party, somewhat experimental projects for other languages (such as manyforJavaScript) but none very popular. Which is a shame, I have to say...
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
So the big argument for making code "self-documenting" is that comments and documentation can get out of date (and lie) and code cannot. But obviously there is no silver bullet and everything you are saying is also very valid.
Are there any languages or environments that enforce commenting and documentation accuracy in some way? Like a compiler that demanded comments be structured a certain way and enforced that they be manually timestamped for correctness if the code they referenced changed? Obviously no system is perfect, but we rely on other pseudo-accurate measures of correctness like testing itself.
Elixir does this, you can check it out at hexdocs.pm/elixir/writing-document...
If you add
in your function doc, and add the DocTest to your test suite, then this examples will run as tests. And yes, this comes built in in the language.
I have to say, it's really awesome checking out the docs for any given library and being confident that the code examples will just work.
Really slick. Definitely seems like Elixir and Elm are two new languages going the extra mile to solve a lot of problems with functional programming while also making developers happy and sane.
In the Javascript realm, I think jsDoc is a must !
It's easy to write, help with auto-completion and "bad parameter" check. If your editor knows how to read it (and it should), it catch a lot of spelling mistakes.
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:
You try writing that kind of stuff in a way that gets automatically checked.
Clojure does not enforce, but you can comment what the function does like:
As Michael noted and Unai exemplified with Elixir, there is this concept of doctests: code snippets with expected outputs to be inserted into documentation, executed and checked. I believe the first and most famous example is Python's doctest module, of which I'm a big fan :) and just got a nice post here in dev.to some days ago. I know there are third-party, somewhat experimental projects for other languages (such as many for JavaScript) but none very popular. Which is a shame, I have to say...