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')
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.
-
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.
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 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')
_Maxxx_ wrote:
which is simply a case of bad commenting in my book - it is not necessary to comment every step
True. The only time I write comments like that is out of aesthetic necessity. If there was a chunk of code above that line that had its own comment, but the comment didn't apply to that line, I might make a comment like that simply to maintain visual consistency.
-
_Maxxx_ wrote:
which is simply a case of bad commenting in my book - it is not necessary to comment every step
True. The only time I write comments like that is out of aesthetic necessity. If there was a chunk of code above that line that had its own comment, but the comment didn't apply to that line, I might make a comment like that simply to maintain visual consistency.
:thumbsup: I came across some code only a few minutes ago which was headed by a "Reset the totals". the next three lines did as advertised. the following six did all sorts of unrelated stuff; even a comment // do unrelated stuff would make it easier to read! ** Caveat. Mine is not the best code in the world, and I am not the 'best' programmer in the world. It's easy to criticise other's code and to say how you would have done it differently; what I objected to in the original case was the assumption that their code was so beautiful it didn't need comments, and that if info was required one should look at the spec (which , in the real world, doesn't actually exist!)
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
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.
[Description("Calculate the tax based on the rate from the database.")]
double CalculateTax(double fine) {
return fine * GetTaxRate();
}Now you can find it via Reflection as well. :cool:
-
I wasn't clear - this was a quote from a cow-worker. My comments, unfortunately, were not KSS so I couldn't post them here.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
I was discussing.
-
[Description("Calculate the tax based on the rate from the database.")]
double CalculateTax(double fine) {
return fine * GetTaxRate();
}Now you can find it via Reflection as well. :cool:
Would't you have to do
[(".esabatad eht morf etar eht no desab xat eht etaluclaC")noitpircseD]
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
Would't you have to do
[(".esabatad eht morf etar eht no desab xat eht etaluclaC")noitpircseD]
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
No, because the compiler doesn't care how you view it.
-
"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')
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!!
-
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!!
So you aren't using source control? :((
-
I wasn't clear - this was a quote from a cow-worker. My comments, unfortunately, were not KSS so I couldn't post them here.
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')
Bollocks.
I wanna be a eunuchs developer! Pass me a bread knife!
-
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')
_Maxxx_ wrote:
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
I agree. It's far too much typing, and excludes reuse of the function. It should be:
// Multiply
return a * b;At least, that's what I'm used to seeing.
I wanna be a eunuchs developer! Pass me a bread knife!
-
"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')
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
-
"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
-
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