Why would you not want to document your source code?

[tvdang7]

I dont want to asking homework questions on here but i am stumped.

I dont see any pro's to NOT document source code. Any help would be appreciated.

 

[nickbits]

Because a lot of the documentation adds no value
Time constraints
Lazy

 

[Schmide]

The best excuse I've heard is: If the code is elegant enough it speaks for itself.

Or I enjoy relearning what I did last week.

 

[Markbnj]

Hmm, sounds like a trick question, but I'll bite. Over-commenting code can break up the structure and make it difficult to read, and many comments are too granular and don't add a lot of value. In my opinion code should be largely self-documenting, and where simply understanding the structure is not enough added comments should explain processes at a business level of abstraction. However, I am a big fan of using the xml documentation facilities of Visual Studio to document the public interfaces of libraries.

 

[dinkumthinkum]

Job security.

 

[Scooby Doo]

Hmmmm how about outdated comments?

 

[tatteredpotato]

However, I am a big fan of using the xml documentation facilities of Visual Studio to document the public interfaces of libraries.

I always have it treat the documentation warnings as errors for just this reason.

 

[Cogman]

Too many comments can be a bad thing as well. If you have more comments then code, you probably have too many (depending on where they are, if they are to define a function, then I'll let that slip, if they are in the code, that is too much).

Outdated comments are worse than no comments. Overall though, comments are a good thing, you just don't want a comment for every line of code.

 

[degibson]

Job security.

Yea but misleading comments are soooo much better.

 

[Cogman]

Yea but misleading comments are soooo much better.

If you want good job security, don't forget to write code that looks like this http://thedailywtf.com/Articles/The-Arralphalet.aspx

 

[tatteredpotato]

Yea but misleading comments are soooo much better.

My favorite are the guys who think they're smarter if they keep variable names under 4 letters, don't use ANY comments (and due to the short variable names, the code isn't even slightly self-documenting), and love putting as many statements on one line as possible (C).

 

[Cogman]

My favorite are the guys who think they're smarter if they keep variable names under 4 letters, don't use ANY comments (and due to the short variable names, the code isn't even slightly self-documenting), and love putting as many statements on one line as possible (C).

You mean statements that look something like this

int c = getD(foo);
int d = c ? foo : foo ? a : b;

I had someone once try to convince me that ?: operators were faster than if statements...

 

[Markbnj]

My favorite are the guys who think they're smarter if they keep variable names under 4 letters, don't use ANY comments (and due to the short variable names, the code isn't even slightly self-documenting), and love putting as many statements on one line as possible (C).

Yeah I was going to suggest short or misleading variable names as a form of job security. We all know how important it is to save space in those source files!

 

[tatteredpotato]

Yeah I was going to suggest short or misleading variable names as a form of job security. We all know how important it is to save space in those source files!

Every '\n' saved counts (Double Points on Windows too!)

 

[tatteredpotato]

You mean statements that look something like this

int c = getD(foo);
int d = c ? foo : foo ? a : b;

I had someone once try to convince me that ?: operators were faster than if statements...

Here's a quick excerpt (not the worst of the lot):

dspmkr(n+3);
    gf3gd.npars += 3;
    gf3gd.areas[gf3gd.npks] = 0.f;
    gf3gd.dareas[gf3gd.npks] = 0.f;
    gf3gd.cents[gf3gd.npks] = gf3gd.ppos[gf3gd.npks];
    gf3gd.dcents[gf3gd.npks] = 0.f;
    gf3gd.npks++;
    for (i = gf3gd.npars - 3; i < gf3gd.npars; ++i) {
      gf3gd.errs[i] = 0.f;
      gf3gd.freepars[i] = 1;
    }
    gf3gd.freepars[gf3gd.npars - 2] = gf3gd.infixw;
    gf3gd.nfp = gf3gd.nfp + 1 - gf3gd.infixw;
    ilo = gf3gd.mch[0] + 1;
    ihi = gf3gd.mch[1] + 1;
    x0 = (float) ((ihi + ilo) / 2);
    gf3gd.pars[gf3gd.npars - 3] = gf3gd.ppos[gf3gd.npks - 1];
    gf3gd.pars[gf3gd.npars - 2] = sqrt(gf3gd.swpars[0] + 
		    gf3gd.swpars[1] * gf3gd.ppos[gf3gd.npks - 1] + 
		    gf3gd.swpars[2] * gf3gd.ppos[gf3gd.npks - 1] * 
				      gf3gd.ppos[gf3gd.npks - 1]);

The struct fields aren't documented (or documented too poorly to matter much).

 

[Cogman]

yucky! the sporadic indentation is the devil.

I can't count the number of times bad indentation has lead people to think their code is doing something it isn't. IE

if(imcool())
   prepareTheWorld();
   sayImCool();

 

[tatteredpotato]

yucky! the sporadic indentation is the devil.

I can't count the number of times bad indentation has lead people to think their code is doing something it isn't. IE

if(imcool())
   prepareTheWorld();
   sayImCool();

Those people need themselves some Python.

 

[Markbnj]

I can beat all that stuff, though I can't post a snippet. Worked a few years back trying to debug some issues in a very old point-of-sale system written in C. The modules were all numbered and named according to number, i.e. "MODULE_0323.C". Within each module the functions were assigned another number, and named as "0323_001()", etc. Global variables were treated similarly. Local variables were usually 1 to 5 characters with random underscores. The whole thing was intended to be supported by accompanying documents that they had stopped updating when Reagan was president. It was all very weird and surreal. I felt like I had stumbled through a mud brick wall into a dim, candle-lit cellar where monks copied ancient manuscripts.

 

[Nothinman]

I dont want to asking homework questions on here but i am stumped.

I dont see any pro's to NOT document source code. Any help would be appreciated.

Laziness combined with the fact that the code seems a lot more obvious when you're writing it than it will months later.

 

[Cogman]

I can beat all that stuff, though I can't post a snippet. Worked a few years back trying to debug some issues in a very old point-of-sale system written in C. The modules were all numbered and named according to number, i.e. "MODULE_0323.C". Within each module the functions were assigned another number, and named as "0323_001()", etc. Global variables were treated similarly. Local variables were usually 1 to 5 characters with random underscores. The whole thing was intended to be supported by accompanying documents that they had stopped updating when Reagan was president. It was all very weird and surreal. I felt like I had stumbled through a mud brick wall into a dim, candle-lit cellar where monks copied ancient manuscripts.

Whats not understandable! There was an error in MODULE_83772B. Variable D2309_1 was greater than 1! Makes perfect sense.

 

[Schadenfroh]

You see, if your code can be followed by others, it means that your job can easily be outsourced. With undocumented (or carefully crafted misleading documentation) spaghetti code, they might try to outsource you, but in less than a month, they will call you and offer you your old job back with a raise.

 

[KIAman]

You see, if your code can be followed by others, it means that your job can easily be outsourced. With undocumented (or carefully crafted misleading documentation) spaghetti code, they might try to outsource you, but in less than a month, they will call you and offer you your old job back with a raise.

If only that were true. Most places are too dumb to realize they need you. From my experience, they'll pay someone or a consultant 5x the money to figure out something you left behind taking 10x the time you could've done it yourself. Then they will pat themselves on the back.

The only legitimate reason I can think of not documenting your code is for security purposes. But even then, encryption is the answer, not obscurity.

 

[Cogman]

If only that were true. Most places are too dumb to realize they need you. From my experience, they'll pay someone or a consultant 5x the money to figure out something you left behind taking 10x the time you could've done it yourself. Then they will pat themselves on the back.

The only legitimate reason I can think of not documenting your code is for security purposes. But even then, encryption is the answer, not obscurity.

In other words, If you want a career in software development, go into the consulting business . (Actually, my older brother does software consulting.)

 

[KentState]

The upper management always talks about documentation and processes out of one side of their mouth. The other side creates projects faster than what anyone can complete. That's the biggest reason why I see a lack of documentation. However, we are free to work over the weekends to get everything documented.

 

[MrChad]

Hmm, sounds like a trick question, but I'll bite. Over-commenting code can break up the structure and make it difficult to read, and many comments are too granular and don't add a lot of value. In my opinion code should be largely self-documenting, and where simply understanding the structure is not enough added comments should explain processes at a business level of abstraction. However, I am a big fan of using the xml documentation facilities of Visual Studio to document the public interfaces of libraries.

Agreed.

I think the biggest problem with code documentation is that it becomes outdated very easily. The original developer may take the time to carefully document and explain a complex class or method, but subsequent developers who are fixing bugs or making enhancements may tend to focus on just updating the source while ignoring the documentation. This is a problem with all documentation though, not just source comments.