Is there a reason why we don't embed the design document for code in the source itself?

Question

Couldn't we write the design documentation for source code within the source itself? I suppose like Doxygen but with the focus taken away from implementation towards design. Essentially (and rather excitingly) you have a nice big chunk of markdown at the end of your source file.

Each time I create a new source file (and begin writing in its crisp white pages) I think to myself it would be nice if the first things written there were notes, thoughts and ideas; an exploration of what the module hoped/needed/dreamed to accomplish. Perhaps proximity to the source code will encourage more frequent and fervent attention to the documentation of it?

Or maybe I should be spending my time crafting self-documenting code.

Answer 1

Something I do a lot is that I first create an empty method stub and put the technical design in it as comment, fleshed out per line. Then, after each line of comment, I write the code that does what the design says.

Answer 2

You can do this - it's called Literate Programming, invented by Donald Knuth. As for self-documenting code, all I can say is that I've never seen any.

Answer 3

One problem with embedding the design in the source code is that the source layout / structure is probably too granular to be documented at a file level - that is covered by writing good, clean, self-documenting code. If you're a refactoring nut you may also have a lot of small files, and documenting each one is pointless (as reading all the notes would be very difficult).

That said, having a more general design note (readme) at the namespace / module / component level can be really useful - an "if I was seeing this for the first time what would I want to know" type of document, written in plain english, and with open questions, decisions etc. clearly noted down.

Answer 4

Who says we don't?

Documentation XML or Doxygen documentation comments (e.g. on a class) are an ideal place to describe how a class works.

Historically the biggest problem with embedded documentation (stored in source files) is that it has to be text-based, making it difficult to write and read, especially where screenshots and diagrams are needed. However, with Visual Studio 2010 it is now easy to embed additional information into source code files (bitmap images, etc) so I think you'll soon see a few extensions appearing that allow you to embed wysiwyg documentation directly into the code.

In the meantime, for more complex documentation where screenshots and diagrams are needed, we simply store our documents in 'Docs' folders alongside the code - so if you wish to use an assembly, the overview/design of the assembly is given by versioned documents that sit right next to the code. That's not quite embedded in the source code, but it's always close to hand when you need it.