I want to address the inline comments issue... In interpreted languages, comments = processor overhead... so use them effectively, yet don't abuse them. In compiled languages comments = compiler overhead, but that is a 1 time deal and the overall effect is only felt if you are compiling a application that takes hours to compile... Then I say, err on the side of abuse...
The more you comment you code, the easier it is for you or someone else to redress it later... Large intro comments for Javadocs or similar are fine for explaining what a class or method is for, but they don't help someone understand "how" it is doing it...
I am the CEO now, and though I insist in continuing to wrote code along with my developers, my developers are very thankful for the amount of comments I placed in the code when the company was young and I did 99% of the work myself...
I have just initiated a rewrite of PHP code I wrote 6 years ago. The developing team would have to rewrite the code completely if they didn't have my robust comments....
I am also initiating a new codign project which will use Java and JSP. The requirements for the development team will include robust commenting... I PAY them for the commenting & coding time, so I expect robust comments, there is no excuses otherwise.
Now, for the comments above about "how" one uses Macromedia and/or Word... I guess I would first say that I have had the opportunity to work with output from many editors than most people. I have used Macromedia products as well as many others, always looking for a "faster" way than hand coding... In the end, I found some good tools that work as RAD environments b ut allow me to keep the power and flexibility of hand coding...
For the guy who codes in MM's code window and views the changes in the preview window, I would say that is a fine way to do it... and you can probably get clean code... the messy code comes from letting the MM code engine do the work for you... You can always tell because you will end up with code fragments that are superfluous... for example
<span style="font-size: 18pt;"></span>
empty span tags is common...
<a href="#"></a>
empty anchor tags is common...
etc.
The important thing is that you stay in control of the code, not let the application control the code...
I want to be clear, also about naming conventions, I agree that good naming conventions are a must, especially on large or distributed projects... But there is more than 1 way to skin a cat, Why anyone would be skinning cats..I don't know... But to claim it is "mature" coding to use 1 method because it was taught in some book and/or some class in basic programming is just rediculous... VB developers adopted those techniques because they had 1) a limited selection of variable types 2) only moderate variable typing.... There are languages that FORCE specific constructs for certain variable types... Basic, which is where MS started when trying to build VB, was one... Such as String variable must begin with "$", etc. These were common... people who worked with the old languages got used to the visual representation of type, and thus when VB, etc. were more name friendly, they searched for a way to maintain that clarity...
I use iNum, sNum, isNum, hasNum, lNum, dNum, fNum, etc. which are C & C++ common naming conventions... camel case and all.... I am sure most of you looking at those have NO trouble figuring out what TYPE each of them would hold...
THUS, my comment, just because it woks for you, doesn't mean it is "right" for everyone, and just because some teacher told you this is the way I expect to see your code does not make it the way everyone should code...
My first CS teacher, back 27 years ago, told me I had to completely plan the code, even write it down before coding a single line of code... he said that this was "good" programming practice.... I NEVER did.... I found that I could code directly into the machine with better accuracy than on paper, I also had bad handwritting... and I felt that code TWICE was a waste of my precious time... I would code it, debug it, add a few bugs on purpose, print it, then fix those added bugs, and print it again... Then I would have him signoff the buggy version as draft code and sign off the fixed version as final code...
He took the app and code printouts and examined them to determine grades... I always got an "A"... I had to add the bugs because perfect draft code was very unlikely in the best of cases, and he would have realized I was NOT following instructions 100%...
The point is, "mature" programming is finding a way that works for you and being consistent... NOT following someone elses rigid ideas... If you are consistent, then you will have easier times understanding your own code months or years later, and others will get adjusted to your coding style when you work in a team, even if you don't have 100% the same styles... AND good comments, inline, make the difference when you are adjusting to the new guys...
I love the conecpt of Javadocs, BUT Javadocs can use inline comments too, if written correctly... The trouble is most developers don't give enough information in the comments, before during or after the code to make the Javadoc generated comments very useful...
I see javadocs with VERY useless information frequently...
