Project Documentation

[aronclark1017]

Trying to package up a small bank account manager project that I have been tempering on for a while. One that is certainly worth something to me. Although I have created methods to whip up quick documents with all fields and properties. I would like something better to reference in order to express the mechanical functions. It is unclear to me about any standardized format for code documentation that exists. I have tried object orientated diagrams with shapes to try and express the mechanical flow of the code. But have settled on text methods using the code blocks and literature. Here is an example

 

[phinds]

Is there a question there somewhere or did you just feel that we needed to know your technique?

 

[FactChecker]

My first question is: Do you have programming/documentation standards for that project? If so, you need to satisfy those.

If not, you might want to look at Doxygen. If you format your code comments correctly, it can generate documentation and graphs. If you are already deep into your program, providing the correctly formatted comments might require a lot of work. You might want to add your own overview to the Doxygen documentation.

 

[aronclark1017]

Is there a question there somewhere or did you just feel that we needed to know your technique?

What do you think of my personal documentation? Are diagrams such as UML a reliable standard for diagrams. If so any reference you have to code examples with UML diagrams would be appreciated.

 

[aronclark1017]

My first question is: Do you have programming/documentation standards for that project? If so, you need to satisfy those.

If not, you might want to look at Doxygen. If you format your code comments correctly, it can generate documentation and graphs. If you are already deep into your program, providing the correctly formatted comments might require a lot of work. You might want to add your own overview to the Doxygen documentation.

I have created my own application where user can navigate class fields, properties, and methods. This application also generates files that simply just list all of that information. But in some projects that are large and complex there seems to be a need for a mechanical diagram especially when memory is low. Here this UML example communicates nothing to me as intended.

 

[phinds]

What do you think of my personal documentation? Are diagrams such as UML a reliable standard for diagrams. If so any reference you have to code examples with UML diagrams would be appreciated.

I have my own style of documentation for use in my own software. It's just blocks of comments as appropriate and not a formal system. If you wanted peoples opinion of your method, you should have ASKED, not make us guess whether or not you were asking a question.

 

[aronclark1017]

I think I am settling on this style here

 

[FactChecker]

I think you are going in a wrong direction. Good documentation requires more than a diagram. Trying to mix code, descriptive text, flows, call-trees, functional dependencies, variable definitions, structure definitions, class definitions, class inheritance, etc. in one diagram would turn into a mess for a moderately-sized program.

ADDED: I recommend that you become familiar with how to use a good documentation generator. I am only familiar with Doxygen. There are several others.

 

[FactChecker]

I think I am settling on this style hereView attachment 366120

This might be fine for a program under 100 lines, or an overview diagram. Keep in mind that successful, useful programs grow. What will this look like if the program is a thousand lines? What about ten thousand lines? There would be an enormous amount of details to document.

ADDED: That is a very good try and I applaud your desire to provide good documentation. You are doing much better than many beginning (and even experienced) programmers. What you have done would be good for a top-level overview. What you want, in addition to that, is some way to take care of the mass of tedious details of documentation without having to do it by hand. If you do all that by hand, it doubles the workload.

 

[pbuk]

I also

It is unclear to me about any standardized format for code documentation that exists.

For C++ code Doxygen is the standard.

If you want to add some diagrams giving an overview that's fine, but only once you have documented every public property and method.

If you use a relational database you should document that too.