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

Can not we write design documents for source code within the source code? I feel like Doxygen, but basically (and rather exciting) you have a big part at the end of your source file with the focus that has taken away from the implementation to the design.

Every time I start writing a new source file (and its crisp white pages), it would be good if the first things were written, notes, thoughts and ideas were; The module which was hoped / wanted / dreamed. Perhaps the proximity of the source code will encourage more and enthusiastic attention to its documentation?

Or maybe I should spend time in preparing self-documentation code.

One problem with embedding the design in the source code is that the source layout / structure is probably too grainy to file at the file level - that is,

covered, writing good, clean, self-documentary code If you are making a recapitulation then you may have too many small files, and the documentation of each one is useless (all the notes will be very difficult to read).

He said, the note (readme) at the more common design notepase / module / component level can actually be useful - a "If I was looking for the first time what I want to know" document The type has been written in plain English, and with open questions, the decision is clearly mentioned below.