Comments?
-
// 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 uses a lot of comments... I HATE source without comments, we have one guy here at work that doesn't use any comments at all, and everybody hates his code! I believe that all good programmers use comments, if I returns to some code I wrote a year ago, I really really really loves my comments. - Anders Money talks, but all mine ever says is "Goodbye!"
-
// 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
Comments? What are comments? :confused:
maXallion
"Is there any Tea on this Spaceship?"
- Arthur Dent -
// 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
It is best to write code that works well AND is readable, with a reasonable amount of comments. I do not create a variable or function without a comment documenting what I expect it to do, it's acceptable range, etc. I might know our printing code inside out right now (I've been writing it) but if I come back to it in a year I'll have no idea what a lot of it does specifically unless I either spend time dissecting it, or I have some comments to guide me. I'd rather not waste time. 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.
-
// 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
Professional programmers comment their code, the rest work in McDonald's. :-O I would immediately fire any of my employees were they to not comment the code. Old Simon
-
Professional programmers comment their code, the rest work in McDonald's. :-O I would immediately fire any of my employees were they to not comment the code. Old Simon
Fire your employees for not commenting code? Wow, you are one harsh employer! ;P If anything I would teach them how to write comments and fire them if they don't comply. X| From the respose I got it seems as if I should start commenting my code better... However I believe that comments should be sparse and should not document the obvious.
-
Fire your employees for not commenting code? Wow, you are one harsh employer! ;P If anything I would teach them how to write comments and fire them if they don't comply. X| From the respose I got it seems as if I should start commenting my code better... However I believe that comments should be sparse and should not document the obvious.
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.
-
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.