It is popular to write documentation in the same file as the code and extract that using software to generate documents. In order to not affect performance, the documentation is written within commented lines, in a DSL designed just for the purpose of that. And that often results in cumbersome source file.

Nowadays, test driven development is popular, and usually tests are written on separate files from the code. Since test files are not run during production, it does not interfere with performance, and hence test are not written within commented lines in a DSL, but are written in the same programming language as the code.

Doesn't it make more sense to write documentation in the same file as tests not in commented lines but in the same programming language using DSL? For each syntactic element like class, method, first a documentation telling the features of it can be written, and then test can follow it. That would make things nicer in my opinion.

I have scripting languages like Ruby in mind if that makes difference.

  • What DSL would you write comments in? It's essentially free-form English (or whatever language you are using). The only formal bits belong to the markup language, and there's very little use in exposing those to the compiler/interpreter of the implementation language. It probably makes the documentation uglier as you have to adjust syntax to make it valid code in the implementation language.
    – user7043
    Commented Jul 7, 2013 at 13:33
  • @delnan As for Ruby, YARD for example, is too complicated. I never liked its syntax. DSL I have in mind is like summary("This method does blah blah"), arguments("x, y, *rest"), example("foo(1, 2, 3)").
    – sawa
    Commented Jul 7, 2013 at 13:35
  • And you think this is an improvement over existing markup languages for documentation (doxygen, reStructuredText, markdown)?
    – user7043
    Commented Jul 7, 2013 at 13:37
  • 1
    Putting the documentation with the tests in and of itself sounds good to me, though some would argue that the tests are the documentation. From my experience that can hold true very much provided the test methods each test one specific thing and have names that describe the test they perform. Commented Jul 7, 2013 at 13:37
  • @delnan I think so. Because those markup languages require its own parsing whereas a language internal DSL will work seemlessly.
    – sawa
    Commented Jul 7, 2013 at 13:38

1 Answer 1


It is popular to write documentation in the same file as the code and extract that using a >software to generate documents.

Yes, that is popular - for software libraries and their documentation. I guess you are talking about that kind of docs (and not, for example, user manuals).

And that often results in cumbersome source file.

Well, that is quite debatable. When done with care, IMHO the documentation is exactly where it belongs - in eyesight of the thing it describes, so when I look at a method signature or implementation, I have also to short description of the intensions of that method at hand.

Doesn't it make more sense to write documentation in the same file as tests not in commented lines but in ordinary language using DSL?

I see some problems here:

  • in your docs, you typically want a general outline of your class, and a description for each public method or property of your class. So the docs follow in structure exactly your classes structure, but your tests have typically a different structure. For a specific method, you will typically have more than one test, for a class you will have a lot tests and for a property you might have no test at all.

  • when you place the docs not directly above a method, you will have to repeat the complete method signature and function name at the docs place, to make the description readable - so this leads to some form of unwanted code repetition. Placing the doc above the method avoids that.

  • docs nearby the documented function have the highest chance to be kept up with the code when something is changed. When you put your docs somewhere else, you lower that chance significantly.

So my answer is - no, I don't like that idea (but I like the question, so +1 for that).

What I like, however, is the idea of using tests as part of the documentation (not the full documentation, they are the examples part, but don't describe the general requirements). The documentation could give references to specific tests showing example behaviour, and a doc extraction tool could use that references to create a formatted document where those examples are included (don't know if such a tool exists, but perhaps this would be a nice new feature for one of the available products).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.