Thread: Documenting your work after a problem is solved from a book

Hi,
I just recently solved a problem from a book which was difficult for me. Now, I would like to document the solution (.pdf/.docx file), so that I can refer to it in the future.

Is there some sort of standard to follow when writing out what the program does, how I came about the solution etc?

Or does the source code just stand for itself?

I program as a hobby. Not sure how it is in the real world. Is there a massive document which details how the source code works or do people just read the source code and try and figure it out?

In large-scale projects, there are usually a number of different documents that describe different aspects and layers of the requirements and solution. At the highest level may be some sort of customer requirements doc, and maybe some simple block diagrams of the major components of the solution. In the middle might be things like UML diagrams, database schemae, etc. At the lowest level would be comments in the code. Many companies have their own set of rules on what needs to be documented and how, however many companies also have no such rules, and documentation may not exist at certain levels, or really at all. Thus the "industry standard" is not very standard.

For small-medium personal projects, I usually just put comments in the code. I usually don't have actual design documentation. This is because, for such projects, I usually can get all (or most) of the design figured out in my head or on scratch paper. This becomes easier and easier the more you program (if you keep challenging yourself with tougher problems, that is). I try to make the code speak for itself as much as possible (good variable/function names and logic design that reads easiily). I also try to think of how the code looks to somebody who has never seen it before, and has maybe only an intermediate level of C knowledge (sometimes that's how I feel coming back to a problem a few weeks/months/years later). Comments are required in at least a few places:

• To document interfaces to modules/libraries/classes/etc. That should describe what the function/class does, and for functions what they return and what the parameters are for, etc. This helps whoever uses you interface/library (including yourself) know what functions to use.
• To document how something works. This is for when you simply can't make the code itself any clearer, yet it is not obvious at first glance how it works.
• To document why I did something the way I did. This may be along the lines of "this deals with rounding issues due to compounding inaccuracy from repeated addition of floating point numbers". Or "the library has a bug, so the following 3 lines are a workaround".

If you find yourself doing things like putting a comment after a variable declaration that simply says what the variable is for, you probably picked a bad name.

If it's more the conceptual solution to a problem you wish to remember, regardless of code, then a simple document with a format like the following may work.

Code:

General problem description
Some paragraphs describing general solution, possibly pseudo code, a few images, links, etc.

Given things like Google docs, that document can be available anywhere, and if you use the headings, you can put a table of contents in there to easily look up old problems as the doc grows. You can even categorize them.

But I would gess that, for 95% of the problems I need to solve, I use Wikipedia. It's like an awesome version of that document I just described, with more problems than just the few I worked on. It's rare that I come across a new, really esoteric problem that Wikipedia can't help me with, where I need to resort to other resources/my own documents.

You can take a look at the Doxygen: Main Page. With correct style comments in your code the documentation could be generated automatically... Most part of it at least.

You can take a look at the Doxygen: Main Page. With correct style comments in your code the documentation could be generated automatically... Most part of it at least.

You can take a look at the Doxygen: Main Page. With correct style comments in your code the documentation could be generated automatically... Most part of it at least.

Originally Posted by MutantJohn

I knew vart was a bot...

And not just any bot also

http://www.daz3d.com/media/catalog/p...gen_popup3.jpg