Sure, this is fine too; I only listed my version as a counterpoint to you must add a comment otherwise nobody will know what approximation you’re using.
As I said in the post: If, at the end of that effort, you still feel comments are necessary, then by all means, add comments. Carefully.
Again, this is not at all what the post is about. Unless those comments remain in the code after you’ve written the function. I’m tempted to delete that sentence because so many people are misunderstanding it.
we need to end this myth that code is EVER as clear as well-written English.
Really? Most of the english I read online is anything but well-written. At least code compiles (or interprets, if that’s your cup of tea).
James -
I disagree. If you are relying on a well-known algorithm, you should identify the specific algorithm. Look up Square Root Approximation in Wikipedia, and I see nothing about the Newton-Raphson method or anything that looks like it will match the code. If I read really carefully, I see a link to Newton’s Method, which in fact does match the algorithm here. That’s only after wasting a huge amount of time reading other approaches which don’t match the given approach.
IMHO, always default to descriptive method names for algorithms, and always include wiki-friendly (or dictionary-friendly, or old-school-encyclopedia-friendly) terms. Therefore:
NewtonRaphsonSquareRootApprox(n)
Or:
/**
* Newton-Raphson Square Root Approximation
*/
NRSquareRootApprox()
Some purists will say too much implementation detail, but IMHO you want that implementation detail in there. If you change the implementation to a different algorithm, it is right and proper that you should have to visit every single use of the method in your codebase to make sure the new algorithm will work as well there as the one you are targetting. And, if it doesn’t, you then end up with NRSquareRootApprox() and ISRSquareRootApprox when you add in an Integer Square Root method for greater speed in some situations.
The other option, adding a constant parameter identifying the specific method, IMHO, is more clutter. The algorithm is fundamentally different, and different methods to attain similar results may require additional parameters (ex, a max iterations parameter might make sense for one approach but not another). You also end up with either an enumeration specific to that one method, or an inability for the compiler to check the validity of the enum being passed in (ie, you have implemented NR and ISR, but not BSR; what happens when the BSR constant is passed in?) The enumeration and the code implementation get too far separated in all but the simplest of algorithms, and so will get out of sync.
I used to believe that well-written code was self-documenting… then I started working with a lot of junior devs!!
My philosophy now is to comment almost EVERY line, explaining the business rules - I find it encourages the junior devs to think about what they are doing. (And if you don’t enforce comment every line then (because developers are all lazy) then the comments drop down to zero very rapidly and you end up with no comments at all.)
For example:
'Get all the customers who live in this state
dim objCustomers As New Customer = Customer.GetWhere(State = 'VA')
'If there are no customers in this state...
if objCustomers.Count = 0 Then
'... then we warn the user
MessageBox.Show(You are ALONE!)
End If
Yes, the comments are strictly unnecessary but they may help someone’s understanding at some point in the future, and they certainly help mine when I am code reviewing, so… they stay!!!
(Has Jeff jumped the shark?)
If you’re saying that comments are useless if they are no clearer than the code, that’s not exactly a revelation.
If you’re saying that well-written code is always clearer than a comment, that’s bo11ocks.
Comments are as much note to self as to anyone else:
I’m maintaining some code, it references some class. The code for the class is three pages long, but I just want to know what the class is there for. Shame that the guy who wrote the class (was it me?) considered that the code was self-explanatory.
I have a constant K_WIDTH=100. Cool, the coder was clever enough not to name it K_W. But why not 200?
Pushed for time, I haven’t had time to refactor as I would have liked. How about a little //TODO? (Or //HACK?)
I’m maintaining some code, there is a 10-line procedure which could be replaced with just one method call. I think. Did the guy who wrote the code think of it? Is there some good reason to use 10 lines that I haven’t seen?
(In C#) If I prefix the comment for my class or method with ///, hey, any client code gets extra information in intellisense. (That’s even more useful if all they’ve got is the dll and no ‘self-evident’ code!)
I have a for loop with 5 method calls inside. Do I have to go and look at the code for the 5 methods to work out why the loop starts at 1 instead of 0?
OK, so all my examples are probably more why than how. My point is that you can ignore comments that are there, but you can’t read comments that aren’t there. Please don’t give any extra ammunition to the ‘write-once, read-never’ cowboys coders who are just too lazy to make the effort.
How about you give us some examples of good and bad comments?
I read english a hell of a lot quicker than I do code, give me a well written comment any day. And sure, give the method, variable whatever a descriptive name but don’t skip the title. CamelCaseIsn’tThatGreatToRead.
PS - And, yes, I still enforce Hungrarian (sic!!) notation - otherwise (especially in case-insensitive VB) you end up with variables called the same thing as your classes, which ends up VERY confusing, especially if you use static methods a fair bit.
Ok, here I go disagreeing with you guys.
These points reflect what would be done in an ideal world. And 2 years ago, I would agree with everything said.
HOWEVER, after working on a Monster of a project for the past two years, I’ve began yearning for comments in code. A lot of my work deals with bug fixes in existing code and I’ve finally quelled my urges to simply rewrite crap that doesn’t work. Here are my reasons:
So, what does one do with messy code when refactoring isn’t an option? I say, comment the hell out of it.
You’ve incorrectly asserted that too many comments are bad, as evidenced by a large chunk of useless comments. Useless comments that add nothing to the code are just that, useless. But for complex methods that take several individual tasks, I like to start out by commenting what those tasks are. When I revisit my code, I can simply read the comments to see a breakdown of each step and what I was thinking at the time, without having to ever look at actual code.
Sure, a simply for loop extracting a value from a bean and placing it in a hashtable is pretty simple to understand if you’re not uses cryptic variables, but I just can’t see that
//loop through bean and place value in hashtable
isn’t still adding value.
I once saw a comment confused in one of tha web applications I support!!
Took some time to realise that this guy who wrote the code years back was refering to XML messages sent to confused.com
There’s a while loop there. In successive iterations r will be something other than n / 2 so n/r won’t be 2 any more
Yeah the Newton-Raphson method is generally called just the Newton method. I agree in some cases it’s best to append a comment explaining a little bit of what’s going on. But what I meant is also something you proved yourself. If I see SquareRootApprox(n) and I know that Newtons method is the most common for approximation of square roots, then I don’t need to look any further into it. But if I see SquareRootApprox(n) or // Newton-Raphson Square Root Approximation, and I don’t know what it is or the specifics of the algorithm and I type either in google… I’m gonna end up reading the same thing. The only other possibility is that the programmer inserts a comment as long as a blog post explaining how the Newton method works… and that just makes everything bloated and hard to maintain.
My issue with comments is that too many comments makes everything uncomfortable and a hell of a lot harder to maintain. I’ve been in situations where I have a file maximized on my 30 inch monitor and I’m looking at huge blocks of comments and 2 or 3 lines of code. I ended up removing the superfluous comments and rewriting a big part of the code. Nevertheless, when we got new developers on board, everyone got up to speed fairly quickly and everyone praised the naming conventions and wise use of comments in the code (which where probably less than 1% of the total lines of comments previously there).
Not sure if you inspired this, or if it’s just a coincidence but it’s a comic that seems kinda relevant to the discussion: http://geekandpoke.typepad.com/geekandpoke/2008/07/good-comments.html
I pretty much only use comments in two circumstances:
When what I’m doing in the code seems to make no (or not enough) sense. These tend to be either things like If you don’t do this way up here, you get an Off-By-One error or else large blocks explaining that some object’s implementation is brain-dead, must be worked around, and ending with Thanks a lot, [object vendor]. Usually [object vendor] = Microsoft, but Crystal Reports has been a suspect in the past.
XML comments intended for Intellisense consumption. This is a recent development for me and I’m still wary about it.
comments are merely words.
It’s easy to make the same mistake with your user interface.
“Oh, this interface is a bit confusing. Let’s put some explanatory text in so that users understand what’s going on.” FAIL.
Pi is exactly three!
@Atario - ‘XML comments intended for Intellisense consumption. This is a recent development for me and I’m still wary about it.’
Are you taking the piss mate, or were you just asleep for the last 7 years?
Yeah. I’ve already talked about it: (but in french)
http://sexycoders.com/index.php/2008-03-13/pourquoi-ne-pas-commenter-son-code/
I think that comments are generally a good thing, as someone said about you can ignore the ones that are there but can’t read the ones that aren’t.
On my daily job I usually have tight deadlines that become tighter near the end, and that makes the code quality start to decay plus I have juniors on my team, so comments are a must. For example I just wrote:
//find cases in where this solution is relevant
//note: Last minute change, may be changed to backend at a later date.
protected function inferRelatedCases(solution:SolutionVo):String
This is not only a note to myself but also for someone in the future that comes across my code and wonders why this is here.