Comments?
-
It stands to reason that comments like int a = 0, b = 0; // create to ints and initialise are plain stupid. But *not* commenting what a nd b are for ( and naming them something intelligent ) is just pure antiproductivity. Christian #include "std_disclaimer.h" People who love sausage and respect the law should never watch either one being made. The things that come to those who wait are usually the things left by those who got there first.
Yes, I agree :rose: - comments and Hungarian Notation (see MSDN) are essential, otherwise code is unmaintainable. :suss: Old Simon
-
// 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
I'm a heavy commenter, probably heavier than most. As stated by others coming back a year later and trying to work out what something does is sooo much easier when there are good comments. I also spend quite a bit of time writing up why I did something in a particular way, and more importantly why I didn't do it in some other way. Often when a problem crops up you work through the code and think hey why didn't I do it this way. Many times I already did, or at least I thought through all of the issues and decided it wasn't appropriate. Documenting these decisions is crucial to me, especially when you're working on a large complex code base. "One" of the problems with a lot of open source projects is inadequate comments, and inadequate documentation. Often the only doc's you get is produced from comments, which is another problem in its own right. There is no excuse for not commenting code afaic. Neville Franks, Author of ED for Windows http://www.getsoft.com
-
Yes, I agree :rose: - comments and Hungarian Notation (see MSDN) are essential, otherwise code is unmaintainable. :suss: Old Simon
Comments - yes, they're essential. Hungarian Notation - definitely not essential. Tomasz Sowinski -- http://www.shooltz.com.pl
-
// 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
The mark of a bad, or at least naive, programmer, for sure. In a nutshell: coding is about communcaition. Many people think that the target is the compiler, but it's not: it's other programmers, or yourself, sometime in the future. I used to think I could make my code self-documenting. It's not practical. You need comments to make it understandable. If your comments are out of date, keep them up to date.
-
Comments - yes, they're essential. Hungarian Notation - definitely not essential. Tomasz Sowinski -- http://www.shooltz.com.pl
$ set mode /flame=on :mad: Oh, I do not agree! I have been looking at the source for HTMLToPDF - a fine free utility which converts HTML to PDF. This has been [1] written and [2] without a coding standard. I find this a big shame - time and effort was invested, with a little more care it would have been twice as maintainable. Professional programmers are proud of their code - how is this possible without Hungarian Notation? If it's worth writing, it's worth writing properly :confused: or is it? $ set mode /flame=simmer :rolleyes: Old Simon
-
$ set mode /flame=on :mad: Oh, I do not agree! I have been looking at the source for HTMLToPDF - a fine free utility which converts HTML to PDF. This has been [1] written and [2] without a coding standard. I find this a big shame - time and effort was invested, with a little more care it would have been twice as maintainable. Professional programmers are proud of their code - how is this possible without Hungarian Notation? If it's worth writing, it's worth writing properly :confused: or is it? $ set mode /flame=simmer :rolleyes: Old Simon
<box owner="Pandora"> : Professional programmers are proud of their code - : how is this possible without Hungarian Notation? Are you suggesting that Hungarian is *good* coding standard? Even MS dumped it away in .NET </box> ;P Tomasz Sowinski -- http://www.shooltz.com.pl
-
<box owner="Pandora"> : Professional programmers are proud of their code - : how is this possible without Hungarian Notation? Are you suggesting that Hungarian is *good* coding standard? Even MS dumped it away in .NET </box> ;P Tomasz Sowinski -- http://www.shooltz.com.pl
Well, I would say that for C++ and C it's good, in that it is obvious what a variable's type and usage is. I have no experience of .NET, so can't comment. What gets me annoyed is a variable such as a buried in 10,000 lines of code. I know what type nRange is, but for a I have to dig all over the code to find the type definition. :( Old Simon
-
Well, I would say that for C++ and C it's good, in that it is obvious what a variable's type and usage is. I have no experience of .NET, so can't comment. What gets me annoyed is a variable such as a buried in 10,000 lines of code. I know what type nRange is, but for a I have to dig all over the code to find the type definition. :( Old Simon
Nobody claims that a is good variable name. Hungarian is about prefixes and suffixes. It's of course matter of personal taste, but for me range sounds *much* better than nRange. Let's stop the flame here :-D Tomasz Sowinski -- http://www.shooltz.com.pl
-
Nobody claims that a is good variable name. Hungarian is about prefixes and suffixes. It's of course matter of personal taste, but for me range sounds *much* better than nRange. Let's stop the flame here :-D Tomasz Sowinski -- http://www.shooltz.com.pl
Nope, Flame is still burning ;P Why not pszRange or nRange ? As was mentioned by someone else, code must be maintainable, code that is hard to maintain costs money - my money :mad: ! I believe all programmers should strive to raise their coding standard to the highest level possible. I've been coding professionally for 20 years, and always find ways to make my code more readable. Now then, let's start on the topic: Programmers Should Learn To Write Documentation :-D Old Simon
-
Yes, I agree :rose: - comments and Hungarian Notation (see MSDN) are essential, otherwise code is unmaintainable. :suss: Old Simon
Hungarian Notation are essential Say it like it is brother! cheers, Chris Maunder
-
Hungarian Notation are essential Say it like it is brother! cheers, Chris Maunder
Code must also be user friendly: http://www.userfriendly.org/ :-O Old Simon
-
Nope, Flame is still burning ;P Why not pszRange or nRange ? As was mentioned by someone else, code must be maintainable, code that is hard to maintain costs money - my money :mad: ! I believe all programmers should strive to raise their coding standard to the highest level possible. I've been coding professionally for 20 years, and always find ways to make my code more readable. Now then, let's start on the topic: Programmers Should Learn To Write Documentation :-D Old Simon
: As was mentioned by someone else, code must be maintainable, : code that is hard to maintain costs money - my money No disagreement here - coding standards are a must. But Hungarian is only one of *many* coding standards. It has its pros and cons, which any project manager enforcing standards should be aware of. For quick overview, visit: http://ootips.org/hungarian-notation.html PS: Chris - maybe the next CodeProject poll should be about Hungarian Notation? Tomasz Sowinski -- http://www.shooltz.com.pl
-
Yes, I agree :rose: - comments and Hungarian Notation (see MSDN) are essential, otherwise code is unmaintainable. :suss: Old Simon
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.
-
The mark of a bad, or at least naive, programmer, for sure. In a nutshell: coding is about communcaition. Many people think that the target is the compiler, but it's not: it's other programmers, or yourself, sometime in the future. I used to think I could make my code self-documenting. It's not practical. You need comments to make it understandable. If your comments are out of date, keep them up to date.
There is another problem with 'self documenting' code, which no one has pointed out. If the code is correct and self documenting then the programmer has to read the code and work out what it is doing. This takes up more time than reading some well written comments. This is true for a correct algorithm and also true for an incorrect algorithm. The difference is that with comments for the correct algorithm, the comments match the code. For the incorrect algorithm, at some point you'll realise that the comments and the code don't match and you can then fix the code. For the case of an incorrect algorithm that is 'self documenting' code all you are doing is reading the code but not knowing that the the intent of the code is incorrect. So you've spent 30 minutes looking at the code, worked out what it does. And then you think 'is this meant to be doing this?'. BEcause there are no comments you can't tell if it is correct or not. Stephen Kellett -- C++/Java/Win NT/Unix variants Memory leaks/corruptions/performance/system problems. UK based. Problems with RSI/WRULD? Contact me for advice.
-
: As was mentioned by someone else, code must be maintainable, : code that is hard to maintain costs money - my money No disagreement here - coding standards are a must. But Hungarian is only one of *many* coding standards. It has its pros and cons, which any project manager enforcing standards should be aware of. For quick overview, visit: http://ootips.org/hungarian-notation.html PS: Chris - maybe the next CodeProject poll should be about Hungarian Notation? Tomasz Sowinski -- http://www.shooltz.com.pl
Hi, Thanks for the link - I hadn't seen it before. Old Simon
-
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.