Programming Question
-
I agree, and I like to use comments. I actually often have more comments than code sometimes (mostly XML documentation comments, those can get quite long, and if they get so long (~35 lines) due to a function that does a number of things, I split that function up to make it manageable). I like comments. They help me when I go back to something and think 'WTF was I thinking there'. Sometimes.
Bob Dole
The internet is a great way to get on the net.
:doh: 2.0.82.7292 SP6a
-
My statement is "flame". You're kidding, right? You also provide an absolutely perfect example of why comments are important:
average_ship_speed
This name is very descriptive. Everyone in your team probably loves it and understands it. Your offsite developers in other states in the US get it too, and use it. Then you send the code to your cheap Canadian outsourcing company and something goes horribly wrong and you lose a Mars orbiter[^].
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
-
My statement is "flame". You're kidding, right? You also provide an absolutely perfect example of why comments are important:
average_ship_speed
This name is very descriptive. Everyone in your team probably loves it and understands it. Your offsite developers in other states in the US get it too, and use it. Then you send the code to your cheap Canadian outsourcing company and something goes horribly wrong and you lose a Mars orbiter[^].
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
No I'm not kidding. Brazen statements, designed to invoke a response outside the area of the question, are flame. You're tagged. The old article to which you refer, does not relate to the question at hand. I know that a missing comma also caused a NASA mishap. But that is beside the point. We are discussing comments. I have publically espoused that comments be minimized. Not eliminated. They are to be replaced by well conceived identifiers drawn from the functional area (other than perhaps i, j, k, etc, when used as indexers). The example, to which you referred, replaced the identifier a with the identifier average_ship_speed. Personally, I find that improved readability immensely. Too often we forget that a failure to provide readable code is a failure to provide maintainable code. Referencing outsourcing, I write code in English. Not because I am an elitist but rather because I speak English as my first language. All of my outsourcing experiences have been with providers who also speak English, but not as their first language. So I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
Gus Gustafson
-
It was unitless :)
Gus Gustafson
-
M Towler wrote:
Whereas the following two appear to me to be worthless and merely clutter up the code. I can tell the first line is getting the tax rate, by the call to the self documenting function, and I know the rest is calculating the value because it is obviously a calculation and it corresponds with what the statement of intent in the function documentation was. // Get the tax rate using the appropriate service double taxRate = GetTaxRate(); // calculate the fine
That comment adds meaning to the code - it tells me that the rate is obtained from a service as opposed to being determined within the function. Your argument would have more vilidity if the function was renamed from GetTaxRate to GetTaxRateFromAppropriateService although even then I would expect some comment within the function to define what "Approprate" means
greldak wrote:
That comment adds meaning to the code - it tells me that the rate is obtained from a service as opposed to being determined within the function.
Actually, that's a poor comment. It tells you about what the GetTaxRate() function is doing.. something this function has no control over nor should it care. What if tomorrow, GetTaxRate() were reimplemented to get a tax rate some other way? Now, at best, the comment here is misleading. At worst, if the remainder of this function depends on that tax rate having been looked up in some service, it will break. So, since the source of the tax rate is unimportant to the code written here, the comment should really read:
// Get the tax rateAnd how is that more helpful than the code itself:double taxRate = GetTaxRate();Like you suggested, if its important that the tax rate is fetched from a service, then the code should read:double taxRate = GetTaxRateFromAppropriateService();Which still probably doesn't need a comment here because what an "appropriate" service is, is defined within GetTaxRateFromAppropriateService().We can program with only 1's, but if all you've got are zeros, you've got nothing.
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
Rubbish. :) /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Code can and should to be self documenting, thus the comments explaining what it does are both unnecessary and harmful. The problem is that claiming that does not automatically make the code self documenting. However, comments explaining why the code does what it does are absolutely necessary. The code itself is not the best place for such comments, they are easier to use when placed into a separate document. Thus, if nothing but "code is self documenting" is said about comments, it is likely the coder does not understand the job. The "provided by specification" part makes me think that is the fact here since specification cannot answer the why. The big WHY is being understood while coding.
77465 wrote:
The code itself is not the best place for such comments, they are easier to use when placed into a separate document.
Do you really believe this? /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
I see nothing wrong with this approach. I work in scientific computing and rarely see commented code. I do not comment my own code. I used to work with Microsoft Dynamics, nothing was commented. IIRC when working with the Source Engine or UT2004 in GD none of the source code had comments. Any comments I have ever seen have simply reflected what was obvious from the function name. If you can't read code how are you doing your job? Naming convention is far more important and far less intrusive. Good documentation in my opinion is far more helpful. If you want to comment use hyperlinks to electronic documentation.
Xittenn wrote:
Good documentation in my opinion is far more helpful.
Do you work in a shop where documentation is manually generated? /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
There's a lot to be said for the idea of self-documenting code... not all of it pleasant. The thing is that, while the code may well document itself perfectly in the mind of its creator, that creator might fail to take into account that many people are not exactly what one might describe as "autodidactic" and thus that self-documentation may well be lost on them. Of course, in a perfect world, people who are unable to understand your code shouldn't be playing with it in the first place... but it's not a perfect world, and ultimately, one has to live with the knowledge that from the moment one's code hits a live environment, the catharsis of creating such brilliance is over, and at that point it becomes prostitution, with the nature of a free-for-all built in. Code is self-documenting only if people of at least as high an intelligence as the original programmer are looking at it... but since every programmer (in his own mind, at least) is more intelligent than every other programmer, that's almost guaranteed not to happen. My personal style is to comment at the start of procedures: "This procedure does [this], and (sometimes) here's the algorithm, rendered down into English for all you lesser mortals to understand." I might occasionally document a flag or something which is being used in a particularly abstruse way (consider, for example, the "reverse" or "multiply" - or whatever you want to call it - flag in some implementations of the Luhn algorithm for calculating checksums in credit card numbers -- that's not obvious at all). Sometimes, the way an algorithm works isn't obvious even though the code itself is amazingly simple: for example, to describe why Euclid's algorithm (for the greatest common divisor of two positive integers) works takes pages and pages of text, involving graphs and discussions of where points converge and so on - even though a function for it looks like this: int GCD(int x, int y) { if ((x==0) || (y==0)) return 0; while (x!=y) if (x>y) x-=y; else y-=x; return x; } So in summary, then, I don't think code can always be said to be self-documenting: if the algorithm itself is abstruse (as is Euclid's algorithm) then no matter how simple the code is, the thing's still going to need to be explained. In cases like Euclid's algorithm, the best documentation may well be a link to a
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
Hi i usually prefer self documenting code, but i write comments in the following cases: 1.- I'm writing an API that will be used by someone else 2.- The code refers to bussiness logic 3.- I'm doing something in a non standard way, usually this comes along with an explanation of why i'm doing it. 4.- I'm implementing a workaround 5.- A piece of code was particularly hard to find or figure it out.
CEO at: - Rafaga Systems - Para Facturas - Modern Components for the moment...
-
I am more of an adherent to the "comments are bad" brigade, so will offer a counter view. To be more precise I agree more with the statement that "all comments are apologies [for not making the code self documenting]". I do like statements of intent, not implementation. In the example given, I like the function comment, it states the intent and required preconditions.
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Whereas the following two appear to me to be worthless and merely clutter up the code. I can tell the first line is getting the tax rate, by the call to the self documenting function, and I know the rest is calculating the value because it is obviously a calculation and it corresponds with what the statement of intent in the function documentation was.
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fineComments like the above make code harder to read IMO just due to volume of text. More importantly they are often not updated perfectly when code is maintained, especially when scripted edits are performed; I have been misled in the past by reading the comments and the two not corresponding and this has cost me time, so I would prefer to just read the code and not be distracted. Also where they are a repeat of the code they fail the DRY principle. Like yourself I do write comments during the process of implementation, if I want to sketch out some pseudo code in a comment then slowly turn it into code (just in case I win the lottery and someone else has to finish it off). The difference for me is that once I have finished the code, the comments will have been almost entirely replaced by the code.
I agree with this sentiment. Further, I feel compelled to comment when there is a pitfall to avoid. /// /// Calculate the tax, taking into account the fine passed. /// Requires that the tax rate is retrievable from the TaxService /// /// Note that we subscribe to a service (CheapTax) that may return an /// undocumented -9999.0 as an error value. Be sure to check for this /// value before continuing. /// double taxRate = GetTaxRate();
-
That's "cow-orker".
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
To continue... "Naturally, I'm not programming anything that requires more thought than a payroll program, and I have a perfect memory and everyone I work with does too, and all of them plan to live forever and never leave my company." 'nuff said.
"Seize the day" - Horace "It's not what he doesn't know that scares me; it's what he knows for sure that just ain't so!" - Will Rogers, said by him about Herbert Hoover
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
No I'm not kidding. Brazen statements, designed to invoke a response outside the area of the question, are flame. You're tagged. The old article to which you refer, does not relate to the question at hand. I know that a missing comma also caused a NASA mishap. But that is beside the point. We are discussing comments. I have publically espoused that comments be minimized. Not eliminated. They are to be replaced by well conceived identifiers drawn from the functional area (other than perhaps i, j, k, etc, when used as indexers). The example, to which you referred, replaced the identifier a with the identifier average_ship_speed. Personally, I find that improved readability immensely. Too often we forget that a failure to provide readable code is a failure to provide maintainable code. Referencing outsourcing, I write code in English. Not because I am an elitist but rather because I speak English as my first language. All of my outsourcing experiences have been with providers who also speak English, but not as their first language. So I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
Gus Gustafson
Hey Gus, I think you're missing my point - that there is always scope for confusion in even the simplest, seemingly "safest" code - but I do appreciate the back-and-forth. However, I must take exception when you say my response is outside the area of question. The original post stated "My code doesn't need comments because it is self documenting" which is an argument I've seen again and again. My reply to you, specifically, was that even something as simple as
average_ship_speedcan cause problems, especially when two different people using two different system (eg Metric and Imperial) consume the same value and have different expectations.gggustafson wrote:
I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
That's important, but with spell-checkers readily available I've found that the biggest issue is not spelling, but rather meaning. I'm sure you read my blog post that discusses the issues with that. Overall I do agree that comments are not a replacement for good coding, and I also feel that good coding cannot be a replacement for good comments. Their is so often scope for ambiguity and even with the best devs I come across problems again and again.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
-
It was unitless :)
Gus Gustafson
I have a friend who enjoys quoting things like this in furlongs per lunar month.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
-
At best, self documenting code can only ever document what the code does, not what it was intended to do. The differences between the two are generally referred to as "bugs".
Yeah, exactly. I'm starting to think that this whole "I don't need to use comments" thing is coming from people misunderstanding what self-documenting code is. Self-documenting code is largely about readability (which is good); it doesn't mean that you never need to use comments. Self-documenting code can reduce the need for comments, but that's not the same as eliminating the need for comments. Whenever I hear programmers making these kinds of over-generalized dogmatic statements, I assume it to be a sign of lack of experience in real-world programming, because I can't imagine how someone can program for years and not run into counterexamples.
-
Hey Gus, I think you're missing my point - that there is always scope for confusion in even the simplest, seemingly "safest" code - but I do appreciate the back-and-forth. However, I must take exception when you say my response is outside the area of question. The original post stated "My code doesn't need comments because it is self documenting" which is an argument I've seen again and again. My reply to you, specifically, was that even something as simple as
average_ship_speedcan cause problems, especially when two different people using two different system (eg Metric and Imperial) consume the same value and have different expectations.gggustafson wrote:
I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
That's important, but with spell-checkers readily available I've found that the biggest issue is not spelling, but rather meaning. I'm sure you read my blog post that discusses the issues with that. Overall I do agree that comments are not a replacement for good coding, and I also feel that good coding cannot be a replacement for good comments. Their is so often scope for ambiguity and even with the best devs I come across problems again and again.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
FYI, knots
Gus Gustafson
-
To continue... "Naturally, I'm not programming anything that requires more thought than a payroll program, and I have a perfect memory and everyone I work with does too, and all of them plan to live forever and never leave my company." 'nuff said.
"Seize the day" - Horace "It's not what he doesn't know that scares me; it's what he knows for sure that just ain't so!" - Will Rogers, said by him about Herbert Hoover
Lol. Speaking as someone who has worked on a number of different payroll programs, I can assure you that they do require a great deal of thought!
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')