Not all documentation is good; in fact, most is bad (in my experience.) It saves time to go right to the code to see how it actually works. When you're reading through the lines, it seems easier and more readable without comments interrupting your train of thought. Doesn't take much imagination, just experience working with a lot of existing code (with sub par comments.) So, I like to be able to think clearly while parsing through code, which is also why I prefer to have all the vars scoped so I stay focused on the important thing, which is this; my understanding of the mechanics of the app, not my ability to recall the smallest detail about syntax. Of course, the syntax itself could be annoyingly written, such that it could interfere with clarity; but so long as it is consistent throughout the code, I just categorize this as dialect.
-----Original Message----- From: Jeffry Houser [mailto:[EMAIL PROTECTED] Sent: Monday, May 09, 2005 7:18 PM To: CF-Jobs-Talk Subject: RE: What makes a programmer look low level Good documentation should show you how it does work. I find it hard to imagine a point where code documentation detracts from code readability, which is what your original complaint was. At 05:43 PM 5/9/2005, you wrote: >Both, but mostly code formatting. The architecture, if applied to framework >properly, can make it that much more easy to pick everything up at a glance. >But for our purposes here, lets just say formatting. The problem with >referring to documentation that tells you what the code or app does is that >it may not have been applied as you think. If I'm doing something with an >app, I want to be sure that I'm doing it with the way it actually does work >as opposed to how I think it should work. Being able to refer to good >documentation is always nice as an option, but is no substitute for running >through the lines and clearly seeing what everything does and how its being >done. > > > >-----Original Message----- >From: Jeffry Houser [mailto:[EMAIL PROTECTED] >Sent: Monday, May 09, 2005 5:07 PM >To: CF-Jobs-Talk >Subject: RE: What makes a programmer look low level > > > When you say "Structure" are you talking about code formatting, or >something different? My impression is that you are referring to "code >formatting" however structure could mean different things, so... > > I'd rather see comments than formatted code. I can read unformatted >code, or format it as I'm reading it. > > If by structure, you mean a well-thought out architected application that >makes use of CFCs / custom tags / UDFs to encapsulate functionality and >data.... > As long as the application architecture was documented, I may not >complain about the lack of excessive comments within in the code (although >I'd still prefer they were there). I'd rather be told what the code does >w/o having to figure out. > >At 04:52 PM 5/9/2005, you wrote: > >Is it just me, or do the comments other developers leave throughout their > >code mostly get in the way of just reading the raw code? Having read >through > >all kinds of existing code, I much prefer to have everything scoped and the > >code arranged in a consistent, logical format for readability. I'd rather > >see structure than comments, basically. So, if the code is difficult to >read > >because of how its structured, rather than because of what it does, that > >would be an indicator of a beginner (or an expert job-security guru.) If >the > >structure of the code is logical, most experienced developers should be >able > >to follow along and understand right off the bat. Comments should be >sparse, > >terse and contain obscure information (not easily seen by parsing through > >the lines) as an indicator for an advanced developer. > > > >Louis Mezo > >LogicSynthesis > >Tel: 240.498.8951 > >[EMAIL PROTECTED] > >http://www.logicsynthesis.com > > > >-- >Jeffry Houser, Web Developer, Writer, Songwriter, Recording Engineer >AIM: Reboog711 | Phone: 1-203-379-0773 >-- >My Company: <http://www.dot-com-it.com> >My Books: <http://www.instantcoldfusion.com> >My Recording Studio: <http://www.fcfstudios.com> >Connecticut Macromedia User Group: <http://www.ctmug.com> > > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Discover CFTicket - The leading ColdFusion Help Desk and Trouble Ticket application http://www.houseoffusion.com/banners/view.cfm?bannerid=48 Message: http://www.houseoffusion.com/lists.cfm/link=i:11:2585 Archives: http://www.houseoffusion.com/cf_lists/threads.cfm/11 Subscription: http://www.houseoffusion.com/lists.cfm/link=s:11 Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.11 Donations & Support: http://www.houseoffusion.com/tiny.cfm/54
