The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.
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.
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!
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 rate
And 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.
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();
Yay hay!!! I KNEW I wasn't the only one out there!
I'll sometimes throw in comments like //Use of array is deliberate and correct or whatever when there's any risk that someone may refactor / fix a "bug" without really thinking it through - apparently there are developers like that
Truly. 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.
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.
Back in the day this used to be called pseudo code and was the only way we were allowed to get through the design process. If we couldn't describe what we wanted to do in comments how could we expect to code it?
CalculateTax() may be a bad name - it may not be specific enough. It's not that far away from DoSomething(). OTOH, provided it's a private method, used in a context where its meaning is obvious, why would it still need comments, especially if its body reads like return amount * db.GetTaxRate()? Oh, you have GetTaxRate() in the same class, and it's accessing the database directly? That's a clear case poor encapsulation, where two classes, one coupled to the persistence layer and one strongly rooted in the business logic are shoved into a single one, and which need to be separated.
I too profoundly dislike comments. I think comments are a code stench (M. Fowler calls them smells, but I think "stench" is more descriptive). Every time I see comments in code I find that they are either useless (the code is quite understandable even without them) or are used to mask other problems (the code absolutely needs some refactoring).
Properly maintaining comments anywhere except in libraries which you develop for use across several projects, which you may plan to distribute without source code, is IMO waste, in terms of agile methods, and should therefore be eliminated.
Comments are also the source of many stupid problems. Since the compiler doesn't check comments, they tend to quickly become buggy, this being the case especially in heavily commented code. Having been bitten by this many times, I tend to disregard comments, and as such heavily commented code is annoying for me, since I have to skip large portions of prose to get to the parts which actually matter - and which I can actually trust.
Also, if you read a C++ header file or a Java or C# class file, and there's maybe 10 lines of comments between any two method or member declarations, you might get a very good understanding of the individual members, but loose the overall understanding of the class you're looking at. This increases the chances of introducing changes which break the overall architectural consistency, or even rightout introduce subtle conceptional bugs which are hard to diagnose.
Really, if your code needs commenting, take a better look at it, and think how you can refactor it into smaller, more specialized functions, with better names. Your code should become easier to read without comments if you do such refactorings. And there's a non-documentation-related gain too: you'll notice that code duplication goes down and your code becomes more compact.
In his book "The art of Unix programming" Eric S. Raymond states that he two most important attributes of user interfaces are discoverability (you can easily find out how to use the UI by playing with it) and transparency (you can easily build a correct mental model of the underlying application's workings by analyzing its user interface). IMO that's the case not just with user interfaces, it's the case with any product created by humans, including source code. If your code needs comments, it lacks at least one of those two properties. If something (really, anything) doesn't have any of those properties, people won't want to use it.
If your actions inspire others to dream more, learn more, do more and become more, you are a leader.-John Q. Adams You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering.-Wernher von Braun Only two things are infinite, the universe and human stupidity, and I'm not sure about the former.-Albert Einstein
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.
You also provide an absolutely perfect example of why comments are important:
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[^].
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.
Last Visit: 31-Dec-99 19:00 Last Update: 8-Mar-21 0:45