6 ms·
It clutters the code. Tests are a form of documentation, but too much in the code, like too many comments, obscures. Higher level unit tests (acceptance tests
by 6ren 13y ago
It clutters the code.
Tests are a form of documentation, but too much in the code, like too many comments, obscures. Higher level unit tests (acceptance tests) can be quite long, especially if there's a lot of setup - unlike their example code. Literate programming tried embedded documentation, but didn't catch on (even with Knuth's backing). Embedding tests makes them easier to keep in sync, but tests are already kept in sync by (hopefully) failing when not. However, their idea of automatically running tests is interesting, so there's no infrastructure to set-up, run etc (though you'd want to be able to disable them).
Nice for teaching.
- ash 13y ago> Literate programming… didn't catch on I would argue literate programming is experiencing a renaissance, thanks to docco: https://github.com/jashkenas/docco https://github.com/jashkenas/docco
- pjmlp 13y agoNot really, I never heard of docco and am yet to see a RFP for a node.js project from my employer's enterprise customers.
- vidarh 13y agoChances are much higher that you've seen the output of Docco or one of the multitude of imitations for other languages.
- e12e 13y agoI think literate coffeescript might be a better example of popularizing literate programming: http://ashkenas.com/literate-coffeescript/ http://ashkenas.com/literate-coffeescript/ There also seems to be some traction for literate Haskell: http://www.haskell.org/haskellwiki/Literate_programming http://www.haskell.org/haskellwiki/Literate_programming I experimented a bit with literate programming on an introductory course in programming using java. It's an interesting experience -- it's very easy to produce a very readable language that is still pretty poor java code, as it becomes so easy to split out fragments and "procedures", rather than follow the more common java class-oriented object orientated way of doing things.
- stiff 13y agoI don't think the story of literate programming can be of any help predicting how well this idea here can work out. Literate programming is not "embedding documentation". The main idea was to separate the order in which the code is read from the order in which the compiler sees it, and it embeds the code in the documentation, not vice versa. It was a very idiosyncratic thing, hard to imagine a team of programmers in a typical current commercial setting, developing a nice LaTeX essay around the actual code of the next social network web-app. As the program grows larger it also gets harder and harder to maintain the "story" around it.
- jashkenas 13y agoThat's not the "main idea". Originally, it was a part of the suggested way to accomplish the goal ... but the main idea is this: > Let us change our traditional attitude to the construction of programs: > Instead of imagining that our main task is to instruct a computer what > to do, let us concentrate rather on explaining to human beings what we > want a computer to do. > — Knuth If your program can be read more as an enlightening explanation of the job-to-be-done, and is more oriented toward the human reader of the code than the machine that will execute it, then you've succeeded. Hopefully, it's clear how a program written in such a way could potentially be beneficial to a large team, trying to understand, modify, and improve it.
- stiff 13y agoIt's like saying the main idea in C was to allow writing programs. At this level of generality it is indistinguishable from tens of projects with similar goals, including also earlier ones.
- tokenrove 13y agoRight, but it's important to emphasize what stiff was talking about, that the structure of the narrative needs to be oriented towards the human instead of the machine, because so many people don't bother to do this and decide that literate programming just means having LaTeX or docbook comments in your code. That total inversion (the code is in the documentation, not the documentation is in the code) is important. (That said, I admit that most modern languages are so much more flexible compared to C or Pascal with regards the ordering of code.)
- tel 13y agoI think that Python's doctests have shown this to be a greyer area than this. Not all tests can fit nicely next to function definitions, but a few well-chosen ones are both fantastic documentation and not too cluttery.
- amenod 13y agoThank you! I never had any idea this kind of things exists in python... I can already see some code that would benefit from this (it would be insane to put it everywhere of course).
- sitkack 13y agoDoc tests are a poor solution precisely because they are difficult to edit. The solved a non-problem and made writing documentation AND tests more difficult. Instead of writing tests in strings, the documentation tool should have been modified to render that code _in_ the documentation.
- tel 13y agoI agree with you in that managing real code in a place that gets less frequently executed is a bear, but I wanted to emphasize the value of having tests very near to the primary documentation for a function. That's a complete win, I feel.
- sitkack 13y agoWhich it totally is! That is why all the functions I test are in pairs suitable for nose or py.test def test_foo(): assert False, "test code for foo" def foo(farb): pass Tests should absolutely be next to the code. The test should make it into the documentation. Code is documentation and should make it into the generated documentation, not the first thing you see but it should be there along with commit history, etc.
- tel 13y agoIf that ended up nicely formatted beneath the definition of `foo` in the documentation I would recommend it wholeheartedly. In practice it doesn't happen, sadly.
- driax 13y agoOn the other hand, inline test does make it easier to write tests while writing the function. Besides many well-written programs already contains inline documentation (not comments) that can be a lot longer than the function they describes. Code folding in a IDE goes a long way to make this bearable.
- stcredzero 13y ago> Code folding in a IDE goes a long way to make this bearable. Code folding in IDEs is an indication that we are doing it wrong -- that is, we human beings are programming computers "wrong." I'm not saying that code folding is a symptom. I'm saying that code folding shows how primitive our means of managing code is. It's as if the mesopotamians somehow invented computers, and because of tradition, all code has to be written as cuneiform on wet clay tablets, then fired in ovens before being read. At least text files in directories are digital, but they are as static and behavior-less as clay tablets, and all of the important relationships therein are expressed as implicit correspondences which programmers have to keep track of in their heads. Code Bubbles is a beacon in the direction we should go. https://www.youtube.com/watch?v=PsPX0nElJ0k https://www.youtube.com/watch?v=PsPX0nElJ0k
- aidenn0 13y agoI think you're completely backwards on this. Code folding in an IDE is an example of a way in which text files aren't necessarily static and behavior-less. I see no reason to move away from an underlying representation as text.
- stcredzero 13y agoI see no reason to move away from an underlying representation as text. A big reason is that otherwise people won't move away from the paradigm of static text files. The best they'll do is text files with little gimmicks attached to them.
- andrewflnr 13y agoCode bubbles looks cool, but I don't see the connection with your point about clay tablets. Any digital data is, by itself, flat and behavior-less, whether it's in the form of traditional files or some specially-designed backing store for something like Code Bubbles. I don't see any point in really trying to hide that base reality. I am in favor of giving links between data a more prominent place in our storage systems. I envision a system where the data is mostly fine-grained trees, like sexprs, where hard-links between trees are first-class entities. But at the end of the day it's just an abstraction over a bunch of bytes.
- acjohnson55 13y agoIf the tests are pages long, that might be a sign that the function could be refactored. Also, the optional type annotations and refinements seem to decrease necessary testing quite a bit, compared to the typical scripting language. I would use this all the time. And as other people mentioned, you can always use the check statement out of band, too.
- qznc 13y agoI think you are both right. D even takes it to the next logical step: Present the unit tests as examples in the API documentation (like Doxygen,Javadoc). It means the API examples are kept in sync. http://qznc.github.io/d-tut/testing.html http://qznc.github.io/d-tut/testing.html
- msutherl 13y agoYou would think we'd have editors by now that could, say, hide all the tests to declutter the code while you're reading it.
- skrishnamurthi 13y agoYou don't have to put the tests right in the middle of code. The `where` form goes with the definition, but a `check` form can float freely. So if you prefer a <Lang>Unit style of testing, where your tests reside in a separate file, you can do that with `check` blocks just fine. However, the `where` tests play into the type-inference story for the language!
- seanmcdirmid 13y ago> It clutters the code. Modern IDEs/code editors can support code folding as well as projections fairly easily. I don't see a problem.