Do you ever just ask... WHY?

[mysticlighthouse]

I believe in code documentation. Nothing is worse than to write some code and come back to it after 3 months and not have a clue what you were thinking. Worse yet is if it is someone else's code that you have to decipher.

But there comes a time when there can be too much documentation. When it alone overshadows the actual project. Case in point... my day job... so my manager comes to me with a simple change that needs to be made, a small enhancement, and I get it done in about 3 hours. Now comes the documentation. After 8 hours, a nice, crisp 56 page document is sent off to our documentation QA team where they pour over it.

The problem is this... why can't the documentation just be in the code as remarks and comments? Which it is after I get done coding! The document readers are never going to touch the code, they are just collecting it for historical purposes and no developer is going to read the 56 page document. We couldn't even if we wanted to because the documents aren't available to the developers! The documentation is nothing more than going line by line through the code to explain it to someone who can't read code. Where is the value in this?

It takes longer to write the documentation than it does to actually write the code and push it out to the production server. Then you have all of the upper management wondering why we are so busy and can't get to other projects. DUH!!! We're writing the documents!

Ok... feel better now that I've vented... I think I'll go and finish up another doc.

[dealercrm]

Sounds like your in the great waters or shall I say molasses of the corporate culture.

Writing a detailed synopsis of line by line code seems like overkill to me. Especially if the audience is a project manager that doesnt know how to read code. You have to ask the question how does it benefit the company?

Is the project manager looking for a business scope of what the code is doing, ok write a brief document for that...

Are the coders or even yourself in need of a common language to communicate complex logic within your coding practices. Well then integrate that into the code. Of course sometimes larger efforts are required when you develop standards for the whole team to utilize in every project.

Bottom line... The right balance of documentation written for the correct audience is always good for successful completion of current projects and the eventual revisit to the project weeks, months, or years down the road.

[TrafficProducer]

code documentation Also!!!

If (x==y) then {
crash;
}

Don't C programmers khow that they must use k, i, x and y; Perl programmers must use foo and bar.

The above is a joke -:)

Code should be self documentating e.g the above:-

If (apples==10) then {
eat_the_apples;
}

By the way what is foo and bar??

[mysticlighthouse]

dealercrm,

You're right, I'm deep in the raging waters of Corporate America. I might even drown. The biggest problem that faces our IT industry today, in my humble opinion, is... upper management.

What does that mean? Well, take it like this... should someone who has never written a program or doesn't even know best practices for coding tell you how you should or shouldn't do that? I think that upper management should be comprised of people that have actually been involved in the work that they are managing... novel concept to be sure!

I've had all the Six Sigma Training and all these management seminars... blah blah blah... what it comes down to is common sense in your work environment and creating an atmosphere that makes people chose to work hard. You can't make someone work hard... you can only provide the right setting for that. People like to choose what they get to do or not do. By choosing they actually feel more in control of their lives and careers and enjoy what they do, thus working harder.

Anyone else feel like they might drown? Someone throw me a life preserver quick.

[davebarnes]

By the way what is foo and bar??

If this is a serious question, then:
1. World War II, GIs invent the term FUBAR. An acronym meaning "F_cked Up Beyond All Recognition".
2. For children, we say: "Fouled Up..."
3. Late 1960s, programmers at DEC (Digital Equipment Corporation) need a term to specify a variable and choose: FOOBAR. Because, FUBAR is only 5 characters and besides, someone would catch on to FUBAR.
4. FOOBAR migrates into every bit of software documentation on the planet because programmers love the pseudo-salacious nature of the term.

,dave

[TrafficProducer]

More about:-

If (x==y) then {
crash;
}

Opps! Sorry to the more mature programmers.

Older computers had such small memory that small variables names may have been the only option.

I think I remember seeing the operator! (one byte) used as a value because this took up less storage than the integer value, usually two bytes. If I remember right this was on the Sinclair ZX80 which had 1 K RAM.

Agh! The Good Old Days.

[ron sheldrick]

I guess I'm what you'd call a mature coder and worked for many years at Reuters, you know the company that really started information Dissemination! (years before the internet)
Anyone that calls themselves a pro always puts remarks in their code, so that if it needs to be changed at a later stage, then it's easy to understand what the code is doing. (even if you wrote the code originally) It's called professional etiquet. It also makes life easy if probelms arise with the program/code and saves valuable time.

oh well back to the rocking chair ...

[ron sheldrick]

External documentation is I agree used mainly for gathering dust, but it is useful for tracing problems i.e logical program flows, explaining what a particular program does etc.
The other thing to remember is that documenting takes time, keeps the customer happy and puts $$$$ in your bank account..

[mysticlighthouse]

Ron,

I wholeheartedly agree. That's why I wrote in my first post in this thread

The problem is this... why can't the documentation just be in the code as remarks and comments? Which it is after I get done coding

I just think that anyone that is going to be using the code should be able to understand what is going on in the file from reading the code and comments.

The high level docs could easily be a couple pages just saying basically what the use of each file is and how it relates to the project as a whole. At least you'd think that managers with no coding experience would prefer that. But that doesn't seem to be the usual case.

[redcircle]

More about:-

If (x==y) then {
crash;
}

Opps! Sorry to the more mature programmers.

Older computers had such small memory that small variables names may have been the only option.

I think I remember seeing the operator! (one byte) used as a value because this took up less storage than the integer value, usually two bytes. If I remember right this was on the Sinclair ZX80 which had 1 K RAM.

Agh! The Good Old Days.

I think that was the same processor my calculator had in highschool

[ron sheldrick]

If it wasn't for us mature coders developing the genre....then you young whippersnappers wouldn't have jobs in IT...
Age & Knowledge should be respected not mocked.
Just remember that on your 50th birthday .lol