Please note that my critique of your code was not meant to be personal. This is the type of thing that comes up in code reviews. We debate the (de-)merits having code look a particular way.
well what can i say .. you've got a lot of critique about a project, the scope, time constraints, etc. of which you're unaware of .. no its not java, or c in a c++ compiler .. no its not a c++ compiler ..
True. I don't know what language you are using. or what sort of time constraints you are dealing with, etc. It's been a while since I was in the software industry. It looked like C. C did not include "//" coments. C++ did. Maybe the standards have changed. I'm not writing the code.
However, "laziness" would be indicated if I was writing it, and didn't submit it to peer-review or look at the language standard to see if my compiler is letting me get away with things not in the standard.
your suggestion that commenting will persuade programmers to "skip" over the actual code is ridiculous .. comments are meant to help developers understand the program's logic, not be a substitute for it .. programmers so lazy to skip over code simply because they are not forced to look at it due to liberal documenting shouldn't be programming anyway .. according to your logic we should remove all documenting and self-explanatory code altogether and effectively force the programmer to scrutizine the code to such a deep level that he might as well write it from the bottom up himself anyway .. it seems counterproductive to me ..
That is not what I said.
I said that comments
that say the same thing as the code are not helpful. They are, infact, a maintenance problem. It is a psychological trick of "mindset". Again, in a code-review situations, when other people are scanning for bugs in your code, having comments like this tend to have people miss bugs. I don't know why it happens, but in my experience, it does.
There are other resons why comments like that are maintainance issues.
The same reasons having code copied-and-pasted in several places is a problem. It makes the code-review process (where others are given your code, so they can scan the code for bugs and clarifications) less helpful, due simply to the amout of reading each reviewer has to do. We are all human,
it is not laziness to want to read less. When I submit code for review, I am asking for a favor, having people have less to read is a courtesy.
finally, like i said .. the code does a nice job speaking "nerd" already .. i prefer to document in "english" .. if that means im documenting for "amateurs" then i suppose i don't have to document for "professionals" since they speak "code" anyway .. also you as a developer have little if any say in the matter of who is and is not hired .. you will only make the life of those who are hired more difficult by poorly documenting .. welcome to the corporate world .. and yes i've been there .. i've had to dissect a comment-less monstrosity ..
If you are calling your peers "nerds", you have other issues also. English is not my first language, and it is not the main language of many programmers. English is, in my opinion, one of the most inconsistent, and illogical laguages there is, but it happened to be the language of those who developed Computer Science. An accident of history.
My point is, people who are hired to program in a language, or review the code, should either know the language or have access to enough reference matierial to know it well soon.
No other engineering profession aims their documentation to other practitioners at the "layperson". They hire tech-writers to do that. If they are making schematics for technician to execute they make another type of documentation. For assembly, they make another.
Comminication to do transfer info. from technical person to tech-writer should be done in several question and answer sessions. Not implicitly through code that gets chucked over the wall.
My point is: you have an audience. Aim your comments at the appropriate audience (I would be surprised if comments to code actually had an audience of people who don't know the programming language, but I guess times really have changed).
i personally would rather make sure that the "amateurs" i work with understand the code properly and save myself the second trip of sitting down with them and explaining the code's logic verbally .. that would be a frustrating experience ..
That seems to me, to be true "laziness". That "frustrating experience" is exactly what you need to have. Hand poeople printed out copies of your code, explain what it is you want it to, and have them scrutinize your code and comments for correctness and clarity. I learnt a lot from these experiences.
by the way, weeding out the "amateurs" isn't always a great thing to do .. some of the greatest programmers started out as "amateurs" .. and finally, i've always believed that those who do not or poorly comment / document are the real amateurs ..
By "ameteur", I meant someone who didn't understand the language you are using. I think you are probably underestamiting your audience here.
And yes comments are needed. Spend a lot of time reverse engineering other peoples code, and have a lot of code reviews, and you will know what type of comments are good, and what are bad. You will also get a feel for what is actually "self-documenting" code (code that doesn't need comments).
Code reviews people, code reviews.