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

 

[Skydiver]

If you look for the Rational Rose product, it can roundtrip between UML diagrams to generated code and back again... Supposedly.

(I only played with it briefly back in the early 2000's. It was okay. Not perfect, but still got rid of a lot of the drudgery. Pricey, thought.)

My personal opinion is that you have a high level UML use case diagram to show the interaction between systems/actors and the goal of each use case. And then you have a UML sequence diagram that shows the sequence calls between systems and actors. And then finally have the class diagrams that shows the methods on them. With proper objects oriented design the methods are more important than the fields/properties because object oriented programming is all about message passing, not the data.*

The sequence diagram will take care of the "mechanical" part that seems to be what you are trying to express in terms of what calls have to happen when.

Unfortunately, you will likely have to draw these UML diagrams or use some tool to do it. I don't think there is a (cheap) way to do this with metadata in the code or comments.

*It took me 10 years to learn that object oriented programming was about message passing, and not the data. I used to be focused on the data because I was all into data structures and algorithms.

 

[aronclark1017]

Unfortunately I'm not familiar with UML diagrams without a code to diagram example from the brief look at examples that are available. It seems that I will need to do more research into these diagrams. Reasonably it seems as if this is a sperate task indeed. Until then I will just do my best to create diagrams that I understand and document with words as best as possible.

 

[Skydiver]

“Programs must be written for people to read, and only incidentally for machines to execute.”
― Harold Abelson, Structure and Interpretation of Computer Programs

To be able to do that you should follow established coding/naming guidelines for the language that you are using. I think I've pointed out in the past that your use of your private version of Hungarian notation, and the use of Java style naming conventions is unusual and will confuse other programmers.

In general, classes should be named with "noun" or "adjective-noun". Method names should follow a "verb-noun" or "verb-noun-adverb", or simply "verb" when the context is well known.

Comment minimally. From industry experience, comments easily fall out of sync with the code if not properly maintained. Let the code be self documenting as much as possible. Use descriptive class, method, property, and variable names.

Do not comment or document the obvious. Now you have to maintain the code and the comment.

// This method logs in the user and return true on success
bool LoginUser()
{
    // Set initial value to 12
    int index = 12;

    // return true to indicate success
    return true;
}

Comment the subtle.

int ComputeMidPoint(int low, int high)
{
    // Although the following looks less verbose:
    //     mid = (low + high) / 2;
    // it is susceptible to integer overflow errors.
    return low + (high - low) / 2;
}

Use design documents and diagrams as high level 10,000 ft roadmaps for the code. There's no need to a document that is in the weeds unless you are writing a court required API document because you're company has been caught in an anti-trust law suite, or you are working with an external vendor that is not allowed to see your source code.