Programming Question
-
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
I feel that level of commenting or descriptive naming would be breaking encapsulation, by exposing the implementation of GetTaxRate. I will go further and say that it would be repeating some of the documentation of GetTaxRate, so fails DRY. This piece of code is simply doing a calculation, so it calls a function to get the rate. It does not really need to have knowledge of where the rate came from to do its task, so it is best not to give it this knowledge. Having minimal information in this function means it will not become out of date when the implementation of GetTaxRate changes, such as to add a local cache of the value obtained from the service, using a database of rates or some other alteration. In summary, what I am really saying is that comments of this type raise the cost of maintenance, as each later change will have to find and change multiple comments in addition to the code itself, or else risk misleading future maintainers.
-
"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 are a number of interesting aspects to the "comment / don't comment" debate. Let's dispose of the easy ones first:
1. Trivial comments. Lord, let me never again see:
i++; // Increment I by one.
...in a subordinate's code.
2. Comments about technique or mechanics. If your code comments are about technology rather than "business logic," they're probably unnecessary. Yes, it's interesting beyond words that you chose a Shell-Metzner sort over the easier to use Quicksort, but "beyond words" is probably where it belongs. Matters of programming technique are easily looked up online or in reference books.
3. Drift, Type 1. As with external documentation, comments can drift away from the code to which they're attached. That doesn't mean the code shouldn't be commented; it merely means that the comments should be maintained along with the code -- and to fail to do so is to fail as a programmer.
Now for the not-so-easy ones:
4. Drift, Type 2. If there has been a significant alteration in the application, such that the earlier "business logic" no longer applies, it will probably -- let's hope, anyway -- have been captured in a revision of a requirements specification. That, of course, will compel significant alterations to the code...but the new "business logic," as instantiated in the code, should still be annotated in comments unless that logic is so trivial as to require no comment whatsoever (e.g., profit = price - aggregate cost of production).
5. Posterity. You, the developer, are prone to think only of your own needs and desires while you're in the process of developing your application. But it's even money or better that you won't be the last programmer to work on that program -- and it's six-five and pick 'em that your successor:
- Won't be nearly as conversant with the application's "business logic" as you've come to be;
- Won't agree with your technique or your coding style in all particulars;
- Will be under serious deadline pressure and could use all the help he can get!
Actually, it can be even worse than that: the guy who picks up your program and tries to fix or modify it could well be very, very junior, and thus exposed to all sorts of hazards you, the senior developer, are (relatively) well protected from. Uncommented code can be a nightmare for such a maintenance programmer, especially as the most junior sorts typically get the dirtiest jobs and are ut
-
I think comments are worth their weight so ling as they are written well - describing the business reasons not the technology (unless the tech is crafty, unusual or complex) when I sit down to write a method, I start by calling it something
public double CalculateTax(double fine)
{
}Then I comment it
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Then I might write some test code just to get it building
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// TODO: Perform the tax calculation
return 34567.89;
}Then I start to flesh out the method by way of comments
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
// calculate the fine (I think it is just fine * tax rate but need to check with spec!)
}Then, finally, I write the code
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fine
tax = taxRate * fine;return tax ;}
That way, I can remember where I was if I get interrupted, the comments aren't an afterthought, they are a part of the process and, if I get hit by the Programmer bus, someone else should be able to see what I was doing. Obv. the example is small and trivial, but that's how I work and I fail to understand the 'don't need comments' brigade. What I do hate is/...
// Multiply the rate by the amount
return rate * amount;which is simply a case of bad commenting in my book - it is not necessary to comment every step
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
Yay hay!!! I KNEW I wasn't the only one out there! I'll sometimes throw in comments like
//Use of array[1] is deliberate and corrector whatever when there's any risk that someone may refactor / fix a "bug" without really thinking it through - apparently there are developers like that ;P -
I feel that level of commenting or descriptive naming would be breaking encapsulation, by exposing the implementation of GetTaxRate. I will go further and say that it would be repeating some of the documentation of GetTaxRate, so fails DRY. This piece of code is simply doing a calculation, so it calls a function to get the rate. It does not really need to have knowledge of where the rate came from to do its task, so it is best not to give it this knowledge. Having minimal information in this function means it will not become out of date when the implementation of GetTaxRate changes, such as to add a local cache of the value obtained from the service, using a database of rates or some other alteration. In summary, what I am really saying is that comments of this type raise the cost of maintenance, as each later change will have to find and change multiple comments in addition to the code itself, or else risk misleading future maintainers.
Agreed. It's just my way of viewing this, but I think that simpler is better when writing (and later reading) code, so adding comments that just repeat what the code is already saying or expose some behavior that whoever is using it just don't need to know is failing this principle. That's not to say that any comment is bad either, and I really liked the "comment first and them code and remove the comment" approach!
-
Yay hay!!! I KNEW I wasn't the only one out there! I'll sometimes throw in comments like
//Use of array[1] is deliberate and corrector whatever when there's any risk that someone may refactor / fix a "bug" without really thinking it through - apparently there are developers like that ;PTruly. When I am doing somethings that either is hard to figure out, not intuitive, or appears at first to be solutions in search of refactoring (but in reality is not), I like a comment to remind me why I did it the way I did, and to let others know there is a reason for the funky implementation.
-
"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')
Yes, because it's a lot easier to go to some unrelated business documentation and try to find the requirement which ties to this piece of code than it is to write a line or two in the file already being read about why this method exists. Sigh. I hope you're able to get this person educated/fired.
-
"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')
"any business documentation should be provided by the specification and not the code." LOL nope. Code gets updated, specs rarely do, and that's assuming that specs even exist and can be easily found. Business logic is exactly the kind of thing that should be commented, because the logic of the code won't tell you that and specs don't often go into the kind of detail that is needed when debugging a specific implementation. The code tells you what it does, good comments tell you why. The "why" is important, because you need to know what the code should do, not just what it does, because this is what a maintenance programmer really needs to know. I was a maintenance programmer for a long time, and believe me, commenting business logic is important. The alternative is usually running around asking all the other programmers if they remember why this code--written by someone who is no longer there--is doing what it does.
-
I disagree Minimalist Comments[^] Further your statement is flame. Let the discussions continue. Let learning continue.
Gus Gustafson
-
I think comments are worth their weight so ling as they are written well - describing the business reasons not the technology (unless the tech is crafty, unusual or complex) when I sit down to write a method, I start by calling it something
public double CalculateTax(double fine)
{
}Then I comment it
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Then I might write some test code just to get it building
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// TODO: Perform the tax calculation
return 34567.89;
}Then I start to flesh out the method by way of comments
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
// calculate the fine (I think it is just fine * tax rate but need to check with spec!)
}Then, finally, I write the code
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fine
tax = taxRate * fine;return tax ;}
That way, I can remember where I was if I get interrupted, the comments aren't an afterthought, they are a part of the process and, if I get hit by the Programmer bus, someone else should be able to see what I was doing. Obv. the example is small and trivial, but that's how I work and I fail to understand the 'don't need comments' brigade. What I do hate is/...
// Multiply the rate by the amount
return rate * amount;which is simply a case of bad commenting in my book - it is not necessary to comment every step
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
Great comment! I do it pretty much the same way. While I am thinking what the comment should say to me in 5 years, I usually get good insight what the code-approach should be to work best. When I work on my 5 year old code, I many times wish I would have thought the same way 5 years ago. :(
-
"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')
All I can say is B and S! But since you said in a later post that this is from a coworker, you can do want I did when I was once told not to bother with comments in my code... Wait a year and enjoy the puzzled and incredulous looks on their faces as they struggle to read their own code so they can modify it. Then sidle up to them, look over their shoulders and say, "Whatsa matter? Can't remember WHY you told the computer to perform that particular operation?" Be prepared to run or withstand murderous glares. I warned them. I learned my lesson when I had to throw out years of work because I didn't comment code and couldn't figure out how the programs worked, even though I wrote every one of them and they seemed logical at the time. That squishy thing in your head is leaky and given enough time, fine details will fade away.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
I disagree Minimalist Comments[^] Further your statement is flame. Let the discussions continue. Let learning continue.
Gus Gustafson
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
-
There are a number of interesting aspects to the "comment / don't comment" debate. Let's dispose of the easy ones first:
1. Trivial comments. Lord, let me never again see:
i++; // Increment I by one.
...in a subordinate's code.
2. Comments about technique or mechanics. If your code comments are about technology rather than "business logic," they're probably unnecessary. Yes, it's interesting beyond words that you chose a Shell-Metzner sort over the easier to use Quicksort, but "beyond words" is probably where it belongs. Matters of programming technique are easily looked up online or in reference books.
3. Drift, Type 1. As with external documentation, comments can drift away from the code to which they're attached. That doesn't mean the code shouldn't be commented; it merely means that the comments should be maintained along with the code -- and to fail to do so is to fail as a programmer.
Now for the not-so-easy ones:
4. Drift, Type 2. If there has been a significant alteration in the application, such that the earlier "business logic" no longer applies, it will probably -- let's hope, anyway -- have been captured in a revision of a requirements specification. That, of course, will compel significant alterations to the code...but the new "business logic," as instantiated in the code, should still be annotated in comments unless that logic is so trivial as to require no comment whatsoever (e.g., profit = price - aggregate cost of production).
5. Posterity. You, the developer, are prone to think only of your own needs and desires while you're in the process of developing your application. But it's even money or better that you won't be the last programmer to work on that program -- and it's six-five and pick 'em that your successor:
- Won't be nearly as conversant with the application's "business logic" as you've come to be;
- Won't agree with your technique or your coding style in all particulars;
- Will be under serious deadline pressure and could use all the help he can get!
Actually, it can be even worse than that: the guy who picks up your program and tries to fix or modify it could well be very, very junior, and thus exposed to all sorts of hazards you, the senior developer, are (relatively) well protected from. Uncommented code can be a nightmare for such a maintenance programmer, especially as the most junior sorts typically get the dirtiest jobs and are ut
:thumbsup::thumbsup::thumbsup: Been there, done that, have tooo many t-shirts. I used to work with S/370 Assembler programmers who would tell me it was a waste of time to comment the code since the instruction tells you what it is doing. I made the same argument that it doesn't tell you why. If they weren't telling me not to comment, they were griping the S/370 had too many instructions. As far as they were concerned, you only needed Load, Store, Add, and Branch. I suppose years later they were in nirvana when RISC was announced. Of course they didn't like going through my code since I used (shudder) MACROS and (horrors) symbolic register assignments instead of hardcoded numbers. That last part really blew there minds because I'd have code that read
BALR RTN, PRINT
instead of
BALR 8, PRINT
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
I think comments are worth their weight so ling as they are written well - describing the business reasons not the technology (unless the tech is crafty, unusual or complex) when I sit down to write a method, I start by calling it something
public double CalculateTax(double fine)
{
}Then I comment it
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Then I might write some test code just to get it building
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// TODO: Perform the tax calculation
return 34567.89;
}Then I start to flesh out the method by way of comments
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
// calculate the fine (I think it is just fine * tax rate but need to check with spec!)
}Then, finally, I write the code
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fine
tax = taxRate * fine;return tax ;}
That way, I can remember where I was if I get interrupted, the comments aren't an afterthought, they are a part of the process and, if I get hit by the Programmer bus, someone else should be able to see what I was doing. Obv. the example is small and trivial, but that's how I work and I fail to understand the 'don't need comments' brigade. What I do hate is/...
// Multiply the rate by the amount
return rate * amount;which is simply a case of bad commenting in my book - it is not necessary to comment every step
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
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