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')
-
"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')
The correct response to such a statement is:
"Just because your mother slept with her brother doesn't mean the rest of us will agree it's a good idea."
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
-
"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')
Round flying thing. Discus.
*pre-emptive celebratory nipple tassle jiggle* - Sean Ewington
"Mind bleach! Send me mind bleach!" - Nagy Vilmos
CodeStash - Online Snippet Management | My blog | MoXAML PowerToys | Mole 2010 - debugging made easier
-
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 so agree with that. When I worked, I tried to impart the huge value of Comment First Development. It is always easier to describe what you want to do then it is to write the code. In the trivial cases it can be annoying, especially on accessor methods [properties to you C# boys], but even when you get to something as simple as your tax calc having the comments in place makes a great difference. The second, and not to be ignored, advantage of CFD is that it is very easy to leave off the comment once you've finished the code.
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
-
Round flying thing. Discus.
*pre-emptive celebratory nipple tassle jiggle* - Sean Ewington
"Mind bleach! Send me mind bleach!" - Nagy Vilmos
CodeStash - Online Snippet Management | My blog | MoXAML PowerToys | Mole 2010 - debugging made easier
80's dance clubs Discos
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')
(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
-
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
-
(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
Maximilien wrote:
Stupid/Verbose/Out of sync comments are worse than no comments.
This is similar to the many many dev. arguments where the adage is something done badly is bad - well, of course bad comments are bad - so is bad code! Ill maintained comments can be bad - so can ill maintained code. CODE and COMMENTS are all part of the code base - i don't think they should be thought of as something separate and they should be included in code reviews. A comment that says // Update the Customer for a method public void UpdateCustomer() is obviously a waste of time, and is often the sort of comment that people who don't think they should be made to comment code put in - in a sort of "see, i told you commenting was a waste of time!" But what does UpdateCustomer() do? Does it update the local customer object, persist it to the database, change some properties? Evidently UpdateCustomer is an insufficient comment and an insufficient method name - but ... I think in a sense there are two types of comment... 1. Code comments. This is the sort of comment you are talking about, I think. 2. Business comments - this explains to the programmer the business of the function or code block. A method name of
public StockItem FindTheStockItemWithTheEarliestSellByDateThatIsEitherOfTheTypePassedOrOneOfTheGenericTypesSimilarToThatTypeThatIsAcceptableByTheCustomer(StockType stockType, Customer customer, Date dateToCheck)
{
}Is simply less legible than the equivalent
/*
Find the stock item with the earliest sel by date that is either of the type passed, or one of the generic types, similar to that type, that is acceptable by the customer
*/
public StockItem FindStock((StockType stockType, Customer customer, Date dateToCheck)
{}
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')
... 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.