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

One problem with embedding the de clearly noted down.

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.

Something I do a lot is that I first create an empty method stub and put the technical de.

Documentation XML or Doxygen documentation comments (e.g. On a class) are an ideal place to describe how a class works. Storically 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.

Personally, I'm not a big fan of wysiwyg editors; I feel that the appearence of a document and its content should be separable as I am seldom thinking about one when I am working on the other. I've got to say I'm a little horrified that an IDE would provide the capability of embedding bitmaps in source code :) ... What happens when you open such a file in, say, a non-Microsoft product? But you're right, embedding the documentation in a separate directory in the repository is functionally identical to having it in the source code itself.

– Will Baker Aug 5 '10 at 0:00 'WYSIWYG' documentation is more than just text styles - diagrams and pictures are often vital, which is when I resort to an accompanying . Doc file. VS2010 has the capability to render this sort of external 'metadata' inline with code.

If used well, documentation could be very usefully included into the source code display. That doesn't mean it needs to be stored in the source code. (It is a similar concept to mixing a disassembly and its source code - a very useful visualisation at times) – Jason Williams Aug 5 '10 at 7:38.

I cant really gove you an answer,but what I can give you is a way to a solution, that is you have to find the anglde that you relate to or peaks your interest. A good paper is one that people get drawn into because it reaches them ln some way.As for me WW11 to me, I think of the holocaust and the effect it had on the survivors, their families and those who stood by and did nothing until it was too late.