Programming Question
-
"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')
... and that's when the fight started.
Software Zen:
delete this; -
Simples:
double CalculateTax(double fine) {
var notAComment1 = "Calculate the tax based on the rate from the database.";
return fine * GetTaxRate();
}Seriously, though, I like comments, even for private members. And I like everything (except for constants and member variables, which typically have a corresponding property) to have a comment. I mostly read the comments rather than the code when I'm quickly navigating through code. I don't want a funky looking uncommented section to slow me down. I also write XML comments so intellisense helps me avoid having to go to the definition to find more info.
AspDotNetDev wrote:
even for private members
So you tatoo your privates?
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 -
"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')
In general I agree with the goal of having self-documenting code. However, that's not always possible or feasible. Judicious, and appropriate commenting is as important as well architected and well implemented code. The comments should inform me why you're doing what you're doing, not what you're doing. For that, I can read the code. If it's not immediately obvious from the code why something is being done, then a comment, as short as possible, is necessary. Finally, when the code is updated, please, please update the comments. I've seen too much code where the comments no longer apply.
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 -
"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')
_Maxxx_ wrote:
because it is self documenting, all methods are small and have single functionality
All of those are opinions.
_Maxxx_ wrote:
and any business documentation should be provided by the specification and not the code.
If in fact the business specification is a technical specification and well done it is possible that is true. But since most business specifications are not technical specifications the first part of the assertion becomes questionable. And since many are not kept completely up to date throughout a project the second part assertion is also questionable. Not to mention of course that the second part is...again...an opinion.
-
I initial and date all my code changes in a comment near the change - you have no idea how many times I have been able to point to that in code for a client and say "No, noone has changed this since..." which is particularly handy if something strange goes on...
Silence is golden... but duct tape is silver!! Booger Mobile - My bright green 1964 Ford Falcon - check out the blog here!! | If you feel generous - make a donation to Camp Quality!!
-
(c++ centric answer) Stupid/Verbose/Out of sync comments are worse than no comments. All functions and parameter names should be self-descriptive; use proper user defined types instead of POD (if you have a student ID, let the type be a StudentID instead of a int) All functions should be as simple as possible; they should do 1 thing only; methods should be const if they do not modify the data, Special cases should be fixed by proper code design than by adding a comment in the code (i.e. parameter can be NULL or not, or sometimes ... ), if a method cannot receive a NULL pointer, just change the type to a reference; let the client of that function clean up its own code to not have a null pointer. When there are good coding practice, comments are not "that" necessary, needed in some instances, but not always necessary.
Nihil obstat
-
In general I agree with the goal of having self-documenting code. However, that's not always possible or feasible. Judicious, and appropriate commenting is as important as well architected and well implemented code. The comments should inform me why you're doing what you're doing, not what you're doing. For that, I can read the code. If it's not immediately obvious from the code why something is being done, then a comment, as short as possible, is necessary. Finally, when the code is updated, please, please update the comments. I've seen too much code where the comments no longer apply.
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 Einsteinahmed zahmed wrote:
...is as important as well architected and well implemented code.
Yes but that there is probably the reason comments are needed because after all how many developers do you come across who are willing to say that they are creating code that is poorly architected and poorly implemented? Excluding some (but far from all) beginning programmers I have very seldom come across anyone that felt that they were producing poor code. So one might then conclude that no one should comment code because everyone is producing great code. And then there is also the implicit problem that presumes that that good is the only possible solution that many people would come up with. Thus everyone should understant it in the first place because it is the only possible solution. Rather than one of ten or even one of 100.
-
ahmed zahmed wrote:
...is as important as well architected and well implemented code.
Yes but that there is probably the reason comments are needed because after all how many developers do you come across who are willing to say that they are creating code that is poorly architected and poorly implemented? Excluding some (but far from all) beginning programmers I have very seldom come across anyone that felt that they were producing poor code. So one might then conclude that no one should comment code because everyone is producing great code. And then there is also the implicit problem that presumes that that good is the only possible solution that many people would come up with. Thus everyone should understant it in the first place because it is the only possible solution. Rather than one of ten or even one of 100.
Nothing you've said, while true, negates what I've said. In fact, your statements support what I've said. Note that I said good comments are as important as good code, that goes at least doubly-so for "bad" code. Again, explain why you're doing what you're doing, not what. And yes, I've worked with some people who've admitted to producing "bad" code (myself included). Usually it was only meant to be a short-lived workaround, demo, or prototype, but got left in the product by time crunch or management decision. And, btw, the only viable, real solutions are the ones I come up with! :laugh: ;P :rolleyes:
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 -
Maximilien wrote:
Stupid/Verbose/Out of sync comments are worse than no comments.
However that is also a good indication that code reviews are not occurring or at least they are not being done correctly.
:thumbsup::thumbsup::thumbsup::thumbsup::thumbsup:
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 -
_Maxxx_ wrote:
because it is self documenting, all methods are small and have single functionality
All of those are opinions.
_Maxxx_ wrote:
and any business documentation should be provided by the specification and not the code.
If in fact the business specification is a technical specification and well done it is possible that is true. But since most business specifications are not technical specifications the first part of the assertion becomes questionable. And since many are not kept completely up to date throughout a project the second part assertion is also questionable. Not to mention of course that the second part is...again...an opinion.
opinions, there're like assholes: everyone's got one and they're usually full of shit! :laugh:
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 -
"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')
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.
-
AspDotNetDev wrote:
even for private members
So you tatoo your privates?
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:wtf: Can't talk out of experience but that must hurt like there is no tomorrow. :laugh:
-
"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')
Comments are great when done well. Unfortunately this is rarely the case... The following is a real world example...
// Save the customer.
product.Save();Another one:
// i is the index.
int i = 0;Just call the friggin variable 'index' and drop the comment!
// See mail QQ (it wasn't actually QQ, they were two other initials).
this.DoSomething();Who the hell is QQ and what mail did he send? It's also nice to find change logs in code, comments just for the sake of commenting, comments that describe code that isn't there anymore, a piece of comment that's littered all over your codebase... Comments are lines of code that should be maintained like any other line of code. I hate it when it's perfectly clear to me what a piece of code does, but someone thought it would be nice to still comment it. Now I have to read/adjust the code AND the comment... Comments get out of date, comments lie, comments can be as obscured and unclear as the code itself and comments can be an excuse to write bad code (the code is commented, so it's clear what the code does, right?)... In my opinion comments are a necessary evil at best. The code should speak for itself. Code does not lie and is never outdated. Now it's up to the programmer to make it as clear and readable as possible (unfortunately this is not easy and just straight impossible for some programmers...). But then again, writing good comments is not easy either. I always imagine a writer writing a book. Would he have to comment his paragraphs?
// What I mean to say in the following section is that Frodo takes his ring to Mount Doom to destroy it, but is attacked by the creature we know as Gollum.
(actual text) jkfhadj.kbvadulvkb;jlbn av,lnvaduk aa;vn ;ub jb kgbfleukg vbvs
dfgg afgh;a jafhuhg jdbakjbfjgdfgbukfha afdgfhfdh g fdgfadfgafg fgafdgarerthgaer9df/d.kj fgjdakh
adfg f8oyfagh ahg hgafoihlawr;ahbnfbjn afad;jkh gfnadjkh89fadygUnfortunately that is what a lot of code really looks like... :sigh:
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
} -
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 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 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.
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
-
"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')
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.
-
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
