|
I agree. Comments are evil and should only be used as a last resort. Keep your methods short and simple, don't nest too deeply and pick names that are descriptive. Then your code is self commenting. And you often get to reuse some of the methods.
I would pass on the hungarian also. It clutters the descriptive name and if its type ever changes, you either misdescribe it or you have to edit all references to the new name.
|
|
|
|
|
> Comments are evil and should only be used as a last resort.
> Keep your methods short and simple, don't nest too deeply
> and pick names that are descriptive. Then your code is self
> commenting.
Your code without comments may be self-commenting only to you. This of course depends on the complexity of the algorithms. If you play with toy programs or write classes for UI gadgets clean code may be enough, but I think with real world stuff this picture changes greatly. Non-trivial algorithms require comments - this is the fact of life.
Tomasz Sowinski -- http://www.shooltz.com.pl
|
|
|
|
|
I would say that non-trivial algorithms require refactoring and good naming choices. For most things that require a comment, it is better to introduce a function with an appropriate name. This provides the info the next person might need and allows for the possibilty of reusing the code in another location later.
Sometimes you need to put in comments. But I find it much easier to understand, modify and maintain code that has lots of short, focused methods than code with heavily commented methods that runs on and on.
I do sometimes use comments when stubbing out a method. But I then replace comments with methods calls named to describe what is happening. After that the comment is redundent.
And the toy program I am currently working on is approching 500 KLOC.
|
|
|
|
|
Excuse me that I am so dumb, but what does "500 KLOC" mean?
|
|
|
|
|
500 KLOC ... probably means 500,000 Lines Of Code
|
|
|
|
|
|
>> Sometimes you need to put in comments.
> When?
When after all the naming is as clear as you can get it, methods are split to the smallest logical level that makes sense and things are still not clear from the code itself.
I find it is very rare.
|
|
|
|
|
I would say that non-trivial algorithms require refactoring and good naming choices. For most things that require a comment, it is better to introduce a function with an appropriate name. This provides the info the next person might need and allows for the possibilty of reusing the code in another location later.
Sometimes you need to put in comments. But I find it much easier to understand, modify and maintain code that has lots of short, focused methods than code with heavily commented methods that runs on and on.
I do sometimes use comments when stubbing out a method. But I then replace comments with methods calls named to describe what is happening. After that the comment is redundent.
And the toy program I am currently working on is approching 500 KLOC.
|
|
|
|
|
I would say that non-trivial algorithms require refactoring and good naming choices. For most things that require a comment, it is better to introduce a function with an appropriate name. This provides the info the next person might need and allows for the possibilty of reusing the code in another location later.
Sometimes you need to put in comments. But I find it much easier to understand, modify and maintain code that has lots of short, focused methods than code with heavily commented methods that runs on and on.
I do sometimes use comments when stubbing out a method. But I then replace comments with methods calls named to describe what is happening. After that the comment is redundent.
And the toy program I am currently working on is approching 500 KLOC.
|
|
|
|
|
I agree with you. That's the kind of thing I want to read.
" Sharing ideas to others is better than keeping
to itself"
|
|
|
|
|
Can't pass on the hungarian notation when working in a languages that are loosely typed such as VBScript. (k, you can all stop laughing now.)
Wile in some situations (like C++), it's probably okay, in these cases it becomes very easy for different programmers that have worked on the same code to mixup strings, numbers and booleans. And when you're accessing databases, you've GOT to keep those straight.
|
|
|
|
|
But stupid programmers often change the code and leave the old comments!
Misinformation in the form of comments out of sync with the code are worse than no comments at all. (Oh, and a big chunk of hungarian notation alphabet soup prepending everything doesn't increase understanding). 
Dale Thompson
|
|
|
|
|
>They list the name of the function and the parameters (as if a novice programmer couldn't >figure that out from the code),
But surely the point of having comments is so that you don't have to figure out what the code does. The comments tell you what the code does and reason why it does it.
Comments are there to make our lives easier, not just for decoration. The hardest thing I find though is knowing whether I've commented enough. Just because code looks nice, easy to read, logical when you first write it doesn't mean it'll still look that way 6 months down the road.
Michael
|
|
|
|
|
The key to good comments is to explain _why_ something is being done and not to describe what each line of code is doing. Any single line of code in isolation can be read and understood with easy, but why a block of code is necessary to acheive a solution is not always that obvious.
|
|
|
|
|
Absolutey agree on the "flower box" style comments; those seem to be a sign of a programmer who pays too much attection to what the professor said in CompSci 101, rather than what is sensible and practical. Half the time they have nothing useful to say, the other half they are usually wrong.
OTOH, I don't see how the use of Hungarian and good variable names can eleliminate the need for the following types of comments...
void CCustomSlider::GetTrueChannelRect(CRect& channelRect) const
{
GetChannelRect(channelRect);
// &(*^* Microsoft! The channel rect is wrong if the slider is vertical <sigh>
if ((GetStyle() & TBS_VERT) == TBS_VERT)
{
// Flip the rect 90 degrees
CRect tempRect;
|
|
|
|
|
I agree 100%, especially about what you call "flower boxes".
I hate code littered with comments just for the sake of writing comments.
|
|
|
|
|
I'll insert comment for 5 main reasons:
1) it's an algorithm, how it works and why I choose this
2) It's highly optimized ( and I give the first - unoptimized version into note)
3) It's a bug-fix and I want anyone avoid the same error
4) It's taken from some sources ( book, site, etc.)
5) It's a stupid idea coming from the customer.... Name, date, reference to tell him when he discovered that I had reason...
|
|
|
|
|
Good programmers usually divide a complex function into sub functions to reduce its complexity. It is good to give a very short description of the purpose of the function at the top of each function. It is required because; function names can’t always convey the real job of the function.
Similarly such a short description is good at the beginning of every class definitions.
These kinds of descriptions along will make it easy to reuse or modify the code.
Even though each line of code doesn’t require comments, comments must be provided for complex expressions.
E.g. void (*p[10]) (void (*)());
Without any comments the programmer may time some time to understand such a code.
But if a comment is provided like one given below, its quite easy for the programmer to understand the code.
E.g. void (*p[10]) (void (*)());
/* p is an "array of 10 pointers to a function returning void and taking a pointer to another function that returns void and takes no arguments.*/
|
|
|
|
|
Well good programmers usually dont write lines of code such as:
void (*p[10]) (void (*)());
cause they know they'll confuse the sh*t out of all the bad programmers. So I think your comments about this style of programming is rather silly. I mean sure, there are situations where you might need such lines, but these would be few and far between.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
