Design documentation inline with code.. worth doing?

[sandrewww]

Hey,

This is a general 'best practice' sort of question.

Has anyone ever tried documenting the design of their embedded project inline with their code?

Doxygen is generally used for higher level application/API projects, but there's no reason why you couldn't use doxygen to document an embedded project.

But the real question is, does anyone think documenting an embedded project is worthwhile with doxygen? Or is it better just to document the design, etc in something externally like word?

Thoughts?

[dyeatman]

Since comments don't affect the size of the program I document heavily in
the code. The header in my program with program/project descriptions and
comments is usually 4-5 pages long before you get to any code.
_________________
Google and Forum Search are some of your best tools!!!!

[jbmiller]

I'm from the old school where we just used comments throughout the real code. No need to learn yet another language(doxygen) let alone cross your fingers and hope it interfaces with whatevere project you're working on.
Mind you I only type with 2 or 3 fingers,generally use assembler and believe that simpler is better and faster.even this different colours for differrent lines of 'code' is new to me ! Kinda wished I'd kept my ASR-33 though........

[Wayne_]

I personally hate nothing more than having to trawl through lines of comments placed between code. It actually makes it harder to follow the code.
I also believe that if you know how to program then you shouldn't need a comment for every line.
But, with modern IDE's/editors blocks of comments can be minimised to make reading the code easier.
I also beleive in using sensible names for your vars to make the code easier to understand.
Comments should be small, relevant and show information which is not easily obtainable by looking at the code.

In my opinion

[ckielstra]

Documentation is important, but always keep in mind who you are documenting for. At least always document your interfaces in external documents where customers and the Test team are to considered as well. Meaning:
- A Requirements Specification; your 'contract' with the customer. This is also the input for the Test team.
- A Design Specification; describing the overall architecture. This helps yourself to make up your mind and future developers will get a quick start.

Depending on your organization and project size many other documents might be compulsory (Project Plan, Test Specification, etc.) but to me every (small) project should at least contain the above two documents.

For the rest of the code documentation I prefer the 'self documenting code':
- Use meaningful function and variable names.
- Functions should be small, i.e. fit on one screen.
- Write comments describing the functionality of less obvious code parts.

To me Document generators like Doxygen have limited use. They only copy the text you enter in the source code. But when I have the source code I don't need the generated documents.
The only time I have used the Doxygen documents was when I had to use a library created in an Open Source project. I only wanted to use the library and not dive into the source code, so this was my interface description. A commercial library would perhaps have written a reference manual but in a dynamic Open Source Environment I can understand there are not many people willing to write such a document. Then an automatic Document Generator is better than nothing, in all other projects I've seen it was just a huge sized document to keep management happy (which can be a perfect justification).

[rnielsen]

I like to make comments throughout the entire code. I don't comment every single line but, sometimes, wish I had commented a little more. I don't know how many times I've written something thinking that I'll know what I'm doing in that section of code, just to need to open it up a few years later and think, "what in the heck am I doing here"?

I don't like external documentation, just in case the files get separated somehow. Naming variables to match what they're doing really helps.

Ronald