Comments?
-
Comments are essential. Hungarian notation is absolutely NOT essential. Disk storage is cheap and compilers are not limited to 8 character variable names. Do yourself a favour and do not use hungarian notation. Stephen Kellett -- C++/Java/Win NT/Unix variants Memory leaks/corruptions/performance/system problems. UK based. Problems with RSI/WRULD? Contact me for advice.
Hi, Hungarian has nowt to do with 8 character names - it's about the ability to look at code and see immediately what it does, and also how it does it. Generalization: 10% of the cost of a product is the coding, 30% to 50% maintenance. Good programmers write easily maintainable code. Old Simon
-
Comments? What are comments? :confused:
maXallion
"Is there any Tea on this Spaceship?"
- Arthur Dent>> Comments? What are comments? :confused: << Hmmm... you never need know this, I think. ;P SlavoF "I hear and I forget. I see and I remember. I do and I understand." --Confucius
-
Comments? What are comments? :confused:
maXallion
"Is there any Tea on this Spaceship?"
- Arthur Dent>> Comments? What are comments? :confused: << Hmmm... you will never need to know this, I think. ;P SlavoF "I hear and I forget. I see and I remember. I do and I understand." --Confucius
-
// Hello fellow programmers, // I was just wondering how programmers today use comments in their source code. // I try to minimize the ammount of comments I use since they clutter my code and // get outdated, which can be misleading. // I believe that it is better to write code which is easy to understand than // to write comments which explain what the code is doing. James
You want your comments to state the intention of the code rather than what it says. i.e. A useless comment: i++; // increment i A useful comment: i++; // move to the next record in the SchoolBus table If you always describe what's supposed to happen rather than the code itself, you'll find that the comments will not get outdated so fast. The only exceptions to this rule that I follow is to should comment any areas that use language trickery, math, or places where I have hard coded "magic numbers". Dropping through cases in a switch() statement is a good example of language trickery. Font.Position -= charglyph.aWidth; // Why am I doing this? Font.Position += 1; // magic number - Why are we adding 1? // I won't remember what the 1 is for in a week from now. just my 2c "Harland Pepper, would you stop naming nuts" - Harland Pepper
-
// Hello fellow programmers, // I was just wondering how programmers today use comments in their source code. // I try to minimize the ammount of comments I use since they clutter my code and // get outdated, which can be misleading. // I believe that it is better to write code which is easy to understand than // to write comments which explain what the code is doing. James
Correctly written comments never clutter code. Comments not always describe code statements, they can describe data flow, not trivial algorithms, optimizations, etc... I highly recommend for you to read chapter 19 of the book Code Complete from MS Press, it has great tips for writing comments.
-
>> Comments? What are comments? :confused: << Hmmm... you will never need to know this, I think. ;P SlavoF "I hear and I forget. I see and I remember. I do and I understand." --Confucius
Good! This C++ stuff is complicated enough without any comments! maXallion
"I code, therefore I am!" - The Code Devil
www.maxallion.de - coded evil & more -
// Hello fellow programmers, // I was just wondering how programmers today use comments in their source code. // I try to minimize the ammount of comments I use since they clutter my code and // get outdated, which can be misleading. // I believe that it is better to write code which is easy to understand than // to write comments which explain what the code is doing. James
We have a nice set of coding style guidelines where I work. One of the requirements to pass code review is that the code should be easy to understand. An oft used rule of thumb is: "Remove all text except comments and block boundaries. The resulting text should form a reasonable low-level design doc." This seems to work amazingly well and helps decide when a comment is pertinent, simplistic or superflous. I won't directly address the "comments are for weenies" sentiments in this thread, save to say that support and maintenance is the most expensive part of engineering, and properly commented code directly helps keep these costs down. We're an XP shop - check out http://www-106.ibm.com/developerworks/java/library/j-xp/. It's worth a read. /ravi "There is always one more bug..." http://www.ravib.com ravib@ravib.com
-
Hi, Hungarian has nowt to do with 8 character names - it's about the ability to look at code and see immediately what it does, and also how it does it. Generalization: 10% of the cost of a product is the coding, 30% to 50% maintenance. Good programmers write easily maintainable code. Old Simon
I replied to this by email, but suffice to say that I agree with the points Simon makes except that I think Hungarian notation sucks. Despite having made a successful career start with computer games in 1983 and finding that the majority of people (that I know or have worked with) whose ability I respect do not use hungarian notation, I was rather surpsied to read the Hungarian notation thread here where most of the posters state they use it, although I was pleased to read that most only use it where they felt needed, rather than the impression I got from Simon, which (I may be incorrect) was "must be used all the time". I'm much more in favour of proper descriptive variable names than a cryptic lpcszName, I mean the hungarian part is longer than 'Name'! I think this is on the verge of descending into a religious war of the form of where whitespace should go. So I'll not comment on this any further. Stephen Kellett -- C++/Java/Win NT/Unix variants Memory leaks/corruptions/performance/system problems. UK based. Problems with RSI/WRULD? Contact me for advice.
-
I replied to this by email, but suffice to say that I agree with the points Simon makes except that I think Hungarian notation sucks. Despite having made a successful career start with computer games in 1983 and finding that the majority of people (that I know or have worked with) whose ability I respect do not use hungarian notation, I was rather surpsied to read the Hungarian notation thread here where most of the posters state they use it, although I was pleased to read that most only use it where they felt needed, rather than the impression I got from Simon, which (I may be incorrect) was "must be used all the time". I'm much more in favour of proper descriptive variable names than a cryptic lpcszName, I mean the hungarian part is longer than 'Name'! I think this is on the verge of descending into a religious war of the form of where whitespace should go. So I'll not comment on this any further. Stephen Kellett -- C++/Java/Win NT/Unix variants Memory leaks/corruptions/performance/system problems. UK based. Problems with RSI/WRULD? Contact me for advice.
I believe in standards - and use Hungarian everywhere, and will until something better comes along. Of course, I'm only writing in C and C++ with Hungarian. I farm out my Java and HTML work. ;) What is a tad absurd is that we call ourselves 'professional', yet don't have a standard for the work we do. Old Simon
-
I believe in standards - and use Hungarian everywhere, and will until something better comes along. Of course, I'm only writing in C and C++ with Hungarian. I farm out my Java and HTML work. ;) What is a tad absurd is that we call ourselves 'professional', yet don't have a standard for the work we do. Old Simon
