quote:Original post by The1Blade
If they made a small algorithmical change, then they should tell you where they did it, and then you go and easily figure that one line out yourself.

What if its not an algorithmic change? What if its something about the particular software you are using. I''ll give you an example. Note this is an Oracle PL/SQL statement and not C or C++, but the point is the same.

SELECT ''X''   INTO employee_begin_after_jan_31_1999   from employees   where employees.start_date > TO_DATE(''JAN-31-1999'',''MON-DD-YYYY'' 

Now anyone with any PL/SQL (or SQL) experience and probably a lot without, would be able to see that this is trying to find out if there are any employees that have started after the date of Jan 31/1999. But, wouldn''t it be nice if I added a line of comment to it so that you didn''t need to read the sql statement? Something like:

-- check to see if any employees have started after jan 31/1999SELECT ''X''   INTO employee_begin_after_jan_31_1999   from employees   where employees.start_date > TO_DATE(''JAN-31-1999'',''MON-DD-YYYY'' 

Arguably that hardly adds anything to the code as it would be pretty obvious what my code is doing, but I bet I saved you a few seconds, and when time is money....

Now here is where we get to what my point really was about. What if I change the statement to look like this:

-- check to see if any employees have started after jan 31/1999SELECT ''X''   INTO employee_begin_after_jan_31_1999   from employees   where employees.start_date > TO_DATE(''JAN-31-1999'',''MON-DD-YYYY''     and rownum = 1 

This is an optimization trick. In this case you don''t care how many employees started after jan 31/2000, only that fact that someone has. The ''and rownum = 1'' tells the database server to stop after its found the first one, rather than scan the whole table, which is what it would do without it. If you were inexperienced in sql optimizations or had never seen that before, you might not know what it is there for. A little comment would take care of that.

quote:
Thanks for proving a point of mine, if the good programmers write the code, then it is properly modulized, etc. and the maintenance people could easily figure it out. The only thing that would take thinking are the more complex algorithms, which would take you the same amount of time to figure out with or without comments.

I hardly think I proved a point of yours. I never said ''good programmers'', I said ''more experienced programmers'', they are not necessarily the same thing. And good or not, more experience generally means they have learned more sneaky optimization tricks or a faster (but possibly more convoluted) way of doing things. And I disagree that it would take as much time to figure out the more complicated code with or without comments. But then we are allowed to disagree. We should probably drop this as doubt you will ever convince me that comments are not necessary, and its looking like I will will never convince you or they are.

Bret.

heh.

I am a newbie, and so I am just reading and learning. But I find it interesting that I have never seen such well-commented replies as the ones in this thread. You guys have gone to great trouble to quote each other and intersperse your replies with the other guy''s quotes.

Could it be that context is important? I, for one, need my documentation/comments in close proximity to the code. Whether that means liberal commenting in the code itself, or code snippets in the documentation, it helps me not to have to go back and forth.

IMHO,
- gollumgollum

First, my background, for the sake of you understanding my perspective. I''ve been programming as a hobby for roughly 10 years, with no professional experience. I''m in the last year of a computer science curriculum. I expect I''ll be graduating top of my class. I''ve worked on everything from tiny solo projects to large-scale open-source projects.
I''m not going to even attempt to debate this from the perspective of writing the original code. I neither have enough experience to be definitive nor do I think it''s relevant.
What is relevant is how that code is going to be used. I am not the best programmer on the planet. I cannot easily understand every single piece of code I read. Sometimes I have to spend hours pouring over it, trying to glean the reasoning of some section, even if I know the intent of the function from the general documentation. A few comments inside the code would almost always make that job much easier.
I''m not implying every programmer needs to write down to my level as some of you will only work exclusively with programming geniuses. However, the vast majority of you will have to work with less experienced programmers such as me. These are the people that will be greatly helped by comments.
When I''m out looking for a job for after graduation, I know I''ll be looking for a place like Volition - a place where I feel I won''t be ignored for not being a programming god, but rather one where thoughtful comments will bring me up to speed much quicker. I''ll be quickly dismissing companies with programmers who are too arrogant to realize other, less-skilled people need to work with their code as well.

quote:Original post by Belandrew

First, my background, for the sake of you understanding my perspective. I''ve been programming as a hobby for roughly 10 years, with no professional experience. I''m in the last year of a computer science curriculum. I expect I''ll be graduating top of my class. I''ve worked on everything from tiny solo projects to large-scale open-source projects.
I''m not going to even attempt to debate this from the perspective of writing the original code. I neither have enough experience to be definitive nor do I think it''s relevant.
What is relevant is how that code is going to be used. I am not the best programmer on the planet. I cannot easily understand every single piece of code I read. Sometimes I have to spend hours pouring over it, trying to glean the reasoning of some section, even if I know the intent of the function from the general documentation. A few comments inside the code would almost always make that job much easier.
I''m not implying every programmer needs to write down to my level as some of you will only work exclusively with programming geniuses. However, the vast majority of you will have to work with less experienced programmers such as me. These are the people that will be greatly helped by comments.
When I''m out looking for a job for after graduation, I know I''ll be looking for a place like Volition - a place where I feel I won''t be ignored for not being a programming god, but rather one where thoughtful comments will bring me up to speed much quicker. I''ll be quickly dismissing companies with programmers who are too arrogant to realize other, less-skilled people need to work with their code as well.

I have been programming professionally for 10 years and I have yet to meet a person that could look at a chunk of code and instantly know every detail about it. You are the norm, despite what a few people have seemed to imply here.

Bret.