<div style="font-family: Helvetica; font-size: 13px; ">The most documentation I expect from code is Javadoc-esque blocks before each function/method call, its expected output (especially type), and params. I treat OO programming like every class is its own autonomous black box, and I shouldn't need to spend hours going through the code, to figure out what the expected output should be.<div><br></div><div>Folks, its not hard to write a couple of sentences describing what a function does.</div></div>
<div><div><br></div>-- <br>Cameron Kilgore<br>Sent with <a href="http://www.sparrowmailapp.com/?sig">Sparrow</a><br><div><br></div></div>
<p style="color: #A0A0A8;">On Tuesday, May 8, 2012 at 10:35 AM, Ron Frazier (ALE) wrote:</p>
<blockquote type="cite" style="border-left-style:solid;border-width:1px;margin-left:0px;padding-left:10px;">
<span><div><div><div><br></div><div><br></div><div>Mike Harrison <<a href="mailto:cluon@geeklabs.com">cluon@geeklabs.com</a>> wrote:</div><div><br></div><blockquote type="cite"><div><div>On Mon, 7 May 2012, Jim Kinney wrote:</div><div><br></div><blockquote type="cite"><div><div>On Mon, May 7, 2012 at 9:38 PM, Stephen Haywood <</div><div><a href="mailto:stephen@averagesecurityguy.info">stephen@averagesecurityguy.info</a>> wrote:</div><div><br></div><blockquote type="cite"><div><blockquote type="cite"><div><div><br></div><div>Programmers suck at documentation.</div><div>_______________________________________________</div></div></blockquote><div><br></div><div>Some of us don't :)</div></div></blockquote></div></blockquote><div><br></div><div>Ok, there are exceptions, and that was a generalization.</div><div>Specifically: I suck at documentation, the programmers</div><div>that work for me, with rare exceptions, also suck at documentation. </div><div>I have yet, in my life, never worked with a programmer that was good at</div><div><br></div><div>documentation of their code.</div></div></blockquote><div><br></div><div>Back in the 90's, I was programming for Delta Air Lines in Clipper. I was very good at documenting my code, as I was taught to do at DeVry when I was in school. Almost all functions were modular black box type of things. Every one had a comment header block, which described in detail what the function did, what it's inputs and parameters were, the revision history, and how to use it. Within the code, I would use single line and inline comments to explain what almost every small set of statements did. You could, literally, read my code like a book, even if you'd never seen it before. That probably made it too easy to replace me later, but that's a different story. It was sure helpful months later when I came back and had to modify something and had to recreate the train of thought in my mind to remember what I did before.</div><div><br></div><div>I do believe that almost all programmers either can't, or won't, or perhaps most of all, are not given the time and encouragement to properly document their code. It is hard time consuming work, after all. I suspect most could a very nice job of it if they were given the right environment to do so by management.</div><div><br></div><div>Sincerely,</div><div><br></div><div>Ron</div><div><br></div><blockquote type="cite"><div><blockquote type="cite"><div>You're weird!</div></blockquote><div><br></div><div>I am on the far edges of many bell curves, proudly. :)</div></div></blockquote><div><br></div><div><br></div><div>-- </div><div><br></div><div>Sent from my Android Acer A500 tablet with bluetooth keyboard and K-9 Mail.</div><div>Please excuse my potential brevity.</div><div><br></div><div>(To whom it may concern. My email address has changed. Replying to former</div><div>messages prior to 03/31/12 with my personal address will go to the wrong</div><div>address. Please send all personal correspondence to the new address.)</div><div><br></div><div>(PS - If you email me and don't get a quick response, you might want to</div><div>call on the phone. I get about 300 emails per day from alternate energy</div><div>mailing lists and such. I don't always see new email messages very quickly.)</div><div><br></div><div>Ron Frazier</div><div>770-205-9422</div><div>linuxdude AT <a href="http://techstarship.com">techstarship.com</a></div><div><br></div><div><br></div><div>_______________________________________________</div><div>Ale mailing list</div><div><a href="mailto:Ale@ale.org">Ale@ale.org</a></div><div><a href="http://mail.ale.org/mailman/listinfo/ale">http://mail.ale.org/mailman/listinfo/ale</a></div><div>See JOBS, ANNOUNCE and SCHOOLS lists at</div><div><a href="http://mail.ale.org/mailman/listinfo">http://mail.ale.org/mailman/listinfo</a></div></div></div></span>
</blockquote>
<div>
<br>
</div>