I’ll remember to do this but perl’s plain old documentation is so cool.
I too like to start with comments if I’m writing a new function that I’m not quite sure about. Otherwise I agree.
The other real problem I see is when people don’t keep the comments up-to-date with the rest of the code. As the ‘what’ changes, the ‘why’ can change as well. It’s frustrating when the code says one thing and the comments say another. Which one is right?
And if the code evolves in a way in which it becomes self-explanatory, then by all means, take the comments out.
I wish someone would tell this to my High School and University programming teachers…
Then the .NET Framework code must be bad because I have to comment my code just to document how the framework works. Why can’t we just go back to COBOL? That code was perfectly readable.
I think there’s something to be said for starting with comments. McConnell gives a thorough explanation of why you should, in fact, start with comments before even writing code in chapter 9 of Code Complete 2.
In short, you start by roughing out the design of the function/method/whatever in pseudocode. Then you rework and refactor the pseudocode until it’s as plain as day what you’re doing. Only then do you write the code needed to implement the pseudocode. At the end of the process you’ve still got the pseudocode there to act as comments.
Why delete it? It certainly helps maintenance developers and is a great check to ensure you actually coded the routine you intended to code.
Anyhow, this is just a thumbnail sketch of why you should use comments. For a much better (and more persuasive) argument, check out McConnell’s book. Every professional developer should probably already have a copy anyhow.
I always try to incorporate both ideas in my code. For example, I would write the square root approximation function as
SquareRootApproximation(n)
//Newton-Raphson approximation
{
...
}
That’s just silly, Jeff. You are going to parameterize the algorithm in order to avoid adding one simple comment? You suggest making the function’s interface - and possibly it’s implementation - more complex to avoid a comment? That’s what I’d call a coding horror.
I have to agree with Jason Bunting. Either that, or you are trying too hard to be controversial and drive traffic to your site.
I think to be more precise, your statement should be: comments must reflect and explain the code exactly, all the time.
I don’t care going through a very long comment IF IT HELPS me in the end.
It’s not wrong to start with comments. If you can’t put to paper what you intend to do, how are you going to start coding?
A time when comments are a great and wonderful thing:
Given
-
Code you didn’t write, but need to visit briefly to fix a problem
-
You spend more time than seemed reasonable to figure out what the hell the code was doing, and it wasn’t obvious
Drop a line of comment in with your discoveries so that the next poor sod who has to visit that code won’t waste an hour of THEIR life figuring out what the heck is going on.
{ Before anyone mentions that it would be better to fix the crap: 1) in real life, you don’t always have time to change code to be perfect, and 2) if you do have the time, rewriting code to satisfy an ideal isn’t the best use of the limited number of hours in one’s life, unless it will somehow recover some of those hours at a future date }
I’m going to have to disagree with you too, Jeff. Commenting before you code a method body serves to let you flesh out the method before you spend the time to write the code for it. This ensures that you write what you intended to write, as you have the comment to look back to if you get stuck. Extracting API documentation from your code comments is a beautiful, beautiful thing. That means actually putting API documentation comments in your code.
In a previous entry you complained about the verbosity of code, but today you’re advocating it in order to reduce unnecessary comments? Something doesn’t quite add up.
@fodder
i agree with you…
but may be because im just a junior developer…and im not being sarcastic 
may be experience will make me realize what Jeff and Steve are trying to say out here…mind you Jeff’s SquareRootApproximation(n, Type.NewtonRaphson) is very legible, but there are times when self explanatory function names are not possible. It just saves me a lot of slog with some intelligent comments(or for that matter, even some unintelligent ones)peppered here and there.
Selecting a lighter shade for comments in the IDE makes life a lot easier for me(replacing default dark green in VS2005 to a light blue) to avoid those huge huge blocks of comments from bugging you.
Jeff may be you post one on IDE color scheme. Since your post on consolas font has helped me a lot.
I have to agree with David Avraamides up there about your approximation code.
I code primarily in PHP, and my site uses quite a few includes, so I have to comment to remind myself where certain functions/variables which are being called are located.
It’s rather silly to see so many comments against comments…
Well written comments, or even well placed comments, can save lots of work.
Relying on procedure names to comment?
I usually use the remarks section in c# to explain the why of a method if required.
I do not write many comments except for particularly arcane functions and classes. Sometimes, and Im sure Im not alone, I dont know exactly the best way about doing something but I figure a logical way of doing what I need done. It may not be the best (because I Was not aware of a built in function or a method used to arrive at said conclusion), but it works. However, it works in a very difficult to understand manner (well maybe its just me). This is where I throw comments in.
But quite frankly, Ive maintained code that had comments plastered all over the login scripts. Are you kidding me? First year college students understand login scripts, why the hell are people commenting all over the place?
Mostly I avoid comments, but then I dont use stupid variable names like $b (or var b or Dim b or whatever). Of course, I wouldnt use SquareRootApproximation either (probably sqRtAppx which is perfectly understandable to me).
Too many or wrong comments = bad
so no comments at all = good? What? How about well written and maintained comments that explain what you are doing? (not how you are doing it)
Comments are important, even though in many cases clearer coding does the trick instead. The idea of comments explaining the why instead of the what is nice, but I think I have an even more convincing argument in favor of comments, which runs as follows.
Code, clear as it may be and with the most elegant of naming conventions applied to it, can only ever document itself. That is, such rare self-explanatory code can only document what’s there, never what’s not there. What’s not there is all the different (usually naive) ways the original coder tried to write the code your reading, that were wrong for some reason. The role of comments is thus to explain those inherently unintuitive cases were code isn’t as simple as it might have been in a perfect world. All those hidden pitfalls owing to bugs, support for some legacy design or a 3rd party workaround; all those algorithms that were tried and were found imperfect for the job (that some smarty-pants newcomer may wish to retry on his first day unless warned beforehand); etc. In all these cases, information critical to understanding the what hides in the what not, and can only be exposed by explicit documentation (e.g. comments).
I agree with you Jeff. At least that his example:
SquareRootApproximation(n)
is more than adequate. You may argue that if by looking at the code and reading the procedure name you should almost instanly find that you’re getting squareroots and using an approximation method. The comment will NOT explain the why unless you write a huge comments that honestly defeats the purpose. If the person reading the code is not current with his/her maths… They’ll end up looking it in wikipedia comment or not. The difference is that the people that will see the code at first glance wont lose their time. And the people that don’t get it will end up in the same wikipedia page with the comment or with well named objects anyways.
I have yet to run into to code which was too commented.
‘never, ever start with comments’ … what a load of bollocks. if more people started with comments that outlined what they were attempting to achieve maintenance would be a heck of a lot easier, and so would spotting their bugs.
While I agree that ideally you want to end up with self-documenting code, more often than not you’re writing rubbish on the first pass. And, pragmatically speaking, sometimes, a first pass is all that it gets until you have time to go back over it. When you do have time to go over it, those comments might help you or someone else refactor more efficiently.
It seems more often than not that people don’t write what they mean to write, so comments should help spot bugs and they act like a checksum. In a code review if someone spots the comments differ from the code, then it can be followed up on.
Or just be like everyone else and write code for yourself with little regard to others. Don’t unit test. If it compiles it must works. Phooey.
Just because some people drive like idiots, do you ban cars, or do you punish the idiot?