How do programmers and database engineers remember/track everything?

[Miramonti]

In developing complex programs and databases, what do programmers use (if they use anything) to map everything out in a 'micro-level' so they don't have to relearn it all later when tweaking or adding to the project?

I realize a very good memory is key, but some things can get very complex, and in my case, a good memory is not something to rely on.

 

[Markbnj]

I don't know anybody who maps everything out at 'micro-level', and I think you would go nuts if you tried. Certainly you wouldn't get anything done. I subscribe to Jack Reeves' philosophy that the source code is the design document. If a competent programmer, who has been given a thorough introduction to the problem domain, architecture, process flows, and data models cannot look at the source code and come to an understanding of what is happening, then it is not good source code.

 

[DaveSimmons]

^ right. There just isn't time to write and keep updating extremely detailed design documents for a lot of commercial software.

Aerospace probably does, but their budget per line of code is 10x ours.

Make everyone write clean, maintainable code and comment anything in it that is "tricky," but try to avoid doing something tricky to begin with.

Edit: also, the code base for our main application dates back to 1999 and some parts haven't been touched in 5+ years. I have a good memory but there's no way I can count on remembering why I did something a certain way in 2005. Also, a different developer might be tasked with updating something I wrote or vice versa so the code needs to be clean enough that we can figure out what the other person did.

 

[Ka0t1x]

Technically at work we have nothing like that, even for the database. Source code is always the best route. Although we use ORACLE there's SQL Developer to show you in depth information about a particular database object.

But for notes for our programming framework (PHP), I like to use VooDooPad (Mac only), its a wiki-style notes database. I keep entries based on functions, themed sections (programs based around certain things like Payroll, Finance, etc.). For each entry I try to keep a record of what tables/procedures/views/etc anything pertinent to that section documented. Function pages will have function and args list as well as some examples of common or complex usage. However this is never 100% because the source will always be changing.

 

[squatchman]

It's not too bad until you get above four or five million lines of code in the application. Hopefully you're not storing every source file in the same directory.

Doxygen is great though.

 

[BoberFett]

Object/database diagrams for an architectural overview so you don't have to sift through every object/table trying to remember how everything relates. Once you know what what objects you're dealing with, it's a far more manageable task.

 

[Apathetic]

As others have said - WRITE IT DOWN. Besides documenting the usual class and database structures, I also tend to write down WHY design A was chosen over design B and, if a class was implemented in a very specific way, WHY it was done. You can always reverse engineer the "how" but the "why" may be impossible.

Dave

 

[rchiu]

I don't know if there is any tools out there but in a complex project you have to:
1) modularize (that's when Object Oriented Programming is at it's best)
2) document

if you have well documented component modules, you would know which module you want to enhance if you need to add functions. And of course, nothing can replace the experience of working on the project for a year or two and knowing exactly what the program does and where to change the code if needed. That's why we programmers get the big bucks and job security

 

[Aknosis]

At my work we have bits of pieces of notes stored everywhere in our cvs tree, online wikis and hard copy in folder... Its kinda of all over the place.

But the real answer given above is most notably in the code and proper documenting inline. Our app is php based and the eventual goal will be to use proper documentation techniques to make something like phpdoc output a nice usable document containing every file in our application.

 

[degibson]

This is a great thread.

My suggested addition is this: Write Self-Documenting Code. Give types, classes, variables, etc., names that obviously betray their purpose. These names should mesh with your design doc. If you ever need a comment to explain some actual code, consider re-writing the code itself to be clearer. If it can't be done, then add the comment.

So, to resummarize the thread:
1. Have a vision -- A design document should describe the high-level operation of modules within the project.
2. Modularize -- break tasks and components into small, easy-to-swallow pieces.
3. Document -- beyond the design doc, document behaviors of major modules in detail: in a wiki, in the comments, or both.
4. Self-Document

 

[Dewey]

Self documenting code is a good direction.
Also, nobody reads documents and the get out of date quickly.

 

[Markbnj]

Self documenting code is a good direction.
Also, nobody reads documents and the get out of date quickly.

Precisely. That's why it is so critical for the code to be self-documenting.

 

[IHateMyJob2004]

Use good, sound OO principles and maintain a high level architecture document. Don't be stupid like some people/companies and make the high level architecture document the next great american novel. Typos don't matter. Technical correctness matters.

Our Biggest/best project has one very large model that everything works off of. But that is more of a holder to submodels like network level IO and DB interfaces. Simple fact of the matter is that knowin and using model/view/controller on our project is importnat. No amount of documetnation will teach anyone OO priocnples like MVC. If people don't want to learn no docuemtnation will help these days.

Regarding Java, we/I use Eclpise. If you can't figure out how smaller pieces of a big applcaiton work in a matter of a few hours, one of two things is true. That you don't know how to use the IDE or the software is spaghetti code that uses few if any OO principles. And if your have crap code, no amount of docuemtation will save you. And on top of it, your docuemtnating software that needs to be fixed at that point. And if you ever fix the code and then have to fix the documentation, the costs and headaches will abound.

 

[zebano]

read the source, look at the hardware spec/data sheet and figure it out.