#267277 - 15/10/2005 02:47
Humor For Programmers
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
Probably all of the programmers here are well aware of The Daily WTF, but since I only found it a couple weeks ago, I figured I'd share. Some days are better than others, but this one absolutely cracks me up- unfortunately it seems that this is a rather common occurance, which kind of scares me. The program I'm maintaining at the moment could probably dominate this site but I'm refraining from submitting anything at the moment. I'm still too much in awe of how badly written it is. Anyway, here's hoping the code I wrote in my early years doesn't find its way up onto this site . . . ![](/ubbthreads/images/graemlins/smile.gif)
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267278 - 15/10/2005 08:32
Re: Humor For Programmers
[Re: JeffS]
|
Pooh-Bah
Registered: 21/07/1999
Posts: 1765
Loc: Brisbane, Queensland, Australi...
|
Gold. Pure gold.
_________________________
--
Murray
I What part of 'no' don't you understand?
Is it the 'N', or the 'Zero'?
|
Top
|
|
|
|
#267279 - 15/10/2005 12:19
Re: Humor For Programmers
[Re: muzza]
|
new poster
Registered: 19/08/2005
Posts: 38
Loc: San Diego, CA, USA
|
That reminds me of a student that works with me. He was wanting help on a java assignment, so I looked at his code. All of his veriables were things like "asdf" or "bob."
I spent the whole time I was helping him asking, "what does asdf hold?"
I told him he needs to use descriptive variables and he told me he likes to be annoying to the TA's (graders). I guess he doesn't realize they give him a grade on that stuff.
Anyway, that was my personal WTF yesterday.
_________________________
Mark IIa -- #30103119 -- 70 gig w/ ext3 fs-- Eutronix Light Kit -- Greenlight buttons
|
Top
|
|
|
|
#267280 - 15/10/2005 13:12
Re: Humor For Programmers
[Re: jondle]
|
carpal tunnel
Registered: 24/12/2001
Posts: 5528
|
Quote: I told him he needs to use descriptive variables and he told me he likes to be annoying to the TA's (graders). I guess he doesn't realize they give him a grade on that stuff.
It is surprising how many people try to do that. I used to occasionally help mark code at university for extra beer money and if I couldn't understand it reasonably quickly then they got marks deducted. One guy used a single word as a variable but kept varying which chars were upper and lower case. The code worked but one of the criteria was to have readable code so his mark dropped like a stone. Probably should have submitted that one to the obfuscated C contest...
|
Top
|
|
|
|
#267281 - 15/10/2005 13:32
Re: Humor For Programmers
[Re: tman]
|
carpal tunnel
Registered: 15/08/2000
Posts: 4859
Loc: New Jersey, USA
|
Having been a TA for a few years, I can certainly relate to that. And I would take points off if it became difficult to understand or was not documented. My favorite, though, was when one assignment was handed in by multiple students - you could hold printouts up to the light and have them line up perfectly. So, I would divide the single grade among all of the students that handed that particular paper in, until they got the idea...
_________________________
Paul Grzelak 200GB with 48MB RAM, Illuminated Buttons and Digital Outputs
|
Top
|
|
|
|
#267282 - 15/10/2005 15:44
Re: Humor For Programmers
[Re: pgrzelak]
|
addict
Registered: 24/07/2002
Posts: 618
Loc: South London
|
Slighty OT but....
I've never really understood why some people get majorly obsessive about commenting code - I don't know how many times I've heard "code without comments is bad".
Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere! I know that in practice this isn't always possible, but when I come across a situation like this, a single line comment usually suffices.
Like above, giving variables and functions proper descriptive names is about the biggest favour you can give yourself and others who access the code.
Bad code is bad code, no amount of commenting is going to fix it!
|
Top
|
|
|
|
#267283 - 15/10/2005 16:02
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 24/12/2001
Posts: 5528
|
They have to be good comments as well. I've seen stuff like the following:
Quote: // Increment i
i++;
I guess it could be useful. You might just on the off chance have somebody that doesn't know the programming language being used at all reading it ![](/ubbthreads/images/graemlins/smile.gif)
|
Top
|
|
|
|
#267284 - 15/10/2005 16:47
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 10/06/1999
Posts: 5916
Loc: Wivenhoe, Essex, UK
|
Quote:
Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere! I know that in practice this isn't always possible, but when I come across a situation like this, a single line comment usually suffices.
I couldn't agree more, when I put comments in it tends to be to defend or explain a seemingly odd piece of code. Things like "I know this looks like a strange way to do it, but it is right because...".
_________________________
Remind me to change my signature to something more interesting someday
|
Top
|
|
|
|
#267285 - 16/10/2005 00:10
Re: Humor For Programmers
[Re: andy]
|
carpal tunnel
Registered: 19/01/2002
Posts: 3584
Loc: Columbus, OH
|
I mostly comment when I'm in the situation that I know that I'm going to have to come back and maintain this and I won't know WTF I was thinking the first time through, especially when it comes to documenting the business logic and not just reading the code.
_________________________
~ John
|
Top
|
|
|
|
#267286 - 16/10/2005 09:56
Re: Humor For Programmers
[Re: sn00p]
|
Anonymous
Unregistered
|
Quote: Slighty OT but....
I've never really understood why some people get majorly obsessive about commenting code - I don't know how many times I've heard "code without comments is bad".
Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere! I know that in practice this isn't always possible, but when I come across a situation like this, a single line comment usually suffices.
Like above, giving variables and functions proper descriptive names is about the biggest favour you can give yourself and others who access the code.
Bad code is bad code, no amount of commenting is going to fix it!
I see it as the comments being a higher level to the code. It's not that people can't understand the code itself, it's just faster and easier to understand english than it is to understand any programming language. My philosophy is to be able to read the whole program like a book without looking at one line of code. "// Increment i" is too low level for that.
I used to use little tricks to make each line of code as small and as fast as possible, but in reality, for the average program you can't tell any difference when it runs on today's computers. I also used to find it amusing that no one else could read my code, until I started realizing that I couldn't read it either a week after I wrote it. Now, if it makes it easier to read I'll write a piece of code in several lines when I could do it in one. And now I sort of get a kick out of how easy it is to read my code.
Execution speed and program size are no longer top priorities. Readable and maintainable code is, because processers and hard drives are cheap, but a programmer's time isn't.
|
Top
|
|
|
|
#267287 - 16/10/2005 21:31
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
Quote: I've never really understood why some people get majorly obsessive about commenting code . . Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere
I comment pretty obsessively. In fact, usually I write the comments first and then the code later. This is two-fold for me- first it helps me understand what I'm trying to do later when I (or another programmer) come back to look at it, and second it helps me make sure I've got it straight in my mind before I code it. If I can't explain something, then I'm not ready to write the code yet.
I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.
Consider the following code:
Code:
for (i=0; i<Accounts.Count; i++)
{
Accounts[i].Process();
}
This seems farily straightfoward code, so a comment like "//Loop through our accounts and process them" is not useful. We can see that from the code. However, a comment telling us what the real-world problem is that we're trying to solve is helpful in understanding the bigger picture: "//Calculate new monthly values for each of our accounts based on current market values".
Steve McConnell talks about this in his "Code Complete" book where you should try not to include low-level programming concepts (records, variables, etc.) in your comments but rather talk about real world problems (account, monthly statement, etc.).
I think you can get away with a few high level comments to explain what you're doing, but because I generally tend to write the comments first and describe the process, I end up with many comments sprinkled throughout. I don't think that level is necessary, but I don't think it's a bad thing, either. It's one of those habits that I've found helps me write more robust code.
Edited by JeffS (16/10/2005 21:39)
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267288 - 16/10/2005 23:27
Re: Humor For Programmers
[Re: JeffS]
|
carpal tunnel
Registered: 19/01/2002
Posts: 3584
Loc: Columbus, OH
|
Yeah...that's basically what I said in two lines about documenting business logic ![](/ubbthreads/images/graemlins/smile.gif)
_________________________
~ John
|
Top
|
|
|
|
#267289 - 16/10/2005 23:44
Re: Humor For Programmers
[Re: ]
|
carpal tunnel
Registered: 29/08/2000
Posts: 14489
Loc: Canada
|
Quote:
Execution speed and program size are no longer top priorities.
I've been hearing that myth for 25 years now, and it just never holds water. Unless one doesn't mind having to continuously purchase newer faster hardware to keep up. Ugh.
And of course, the segment I work in -- embedded operating systems -- speed/space are always THE most important thing, after having a working implementation of course.
Cheers
|
Top
|
|
|
|
#267291 - 17/10/2005 00:36
Re: Humor For Programmers
[Re: mlord]
|
Anonymous
Unregistered
|
Quote:
Quote:
Execution speed and program size are no longer top priorities.
I've been hearing that myth for 25 years now, and it just never holds water. Unless one doesn't mind having to continuously purchase newer faster hardware to keep up. Ugh.
And of course, the segment I work in -- embedded operating systems -- speed/space are always THE most important thing, after having a working implementation of course.
Cheers
Well, of course there are exceptions, but I think for the average program that does average tasks on today's desktops, they don't have to worry too much about speed. Of course faster is better, but in my opinion for most situations readable code is more important.
|
Top
|
|
|
|
#267292 - 17/10/2005 07:53
Re: Humor For Programmers
[Re: ]
|
pooh-bah
Registered: 09/08/2000
Posts: 2091
Loc: Edinburgh, Scotland
|
This is because average programs are things like Office etc. Which people expect to take a wee bit to open/edit and so on. I hate that expectation! I remember opening docs in Windows 3.1 and they were FAST. Now there is so much bloat, both in MS Office, and Word documents for example, that it takes ages (relatively speaking)
Running OpenOffice on Linux is better, less bloat......(oops, ranting again, where was I?)
Oh yes, low power or high performance apps - this is when efficient code becomes essential...even though gamers buy zippy machines, there is good impetus for games coders to do this right, and for small embedded apps there is often no other way.
And surely the comments live in the source code...not necessarily in the compiled app.!
_________________________
Rory MkIIa, blue lit buttons, memory upgrade, 1Tb in Subaru Forester STi MkII, 240Gb in Mark Lord dock MkII, 80Gb SSD in dock
|
Top
|
|
|
|
#267293 - 17/10/2005 08:57
Re: Humor For Programmers
[Re: frog51]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
In a desktop app, performance only matters when the difference is perceptable to the user. So if something takes a while to open and you could make it faster, then you should make it faster. If, however, it is a question of a few nanoseconds vs. code readability then readability should take precidence. Now when you're talking a different kind of system nanoseconds could become an issue. It all depends on what kind of app you're developing.
The rule of thumb I go by is to create code that is readable first and optimize when necessary. Trying to optimize code for speed as you write it is generally inneffecient at best, and harmful at worst. Often you'll be defeating compiler optimizations, creating difficult to read code, and not addressing the true bottlenecks anyway. The 80/20 rule applies to optimizations- 20% of the code is going to be responsible for 80% of the performance problems. How's the best way to know what that 20% of the code is? To test it and see- not assume before hand you'll know where the problems are going to be.
This is actually an issue at work right now. My boss has ruled that for new projects, all data access needs to be done via stored procs. Now I am well aware that there is a raging debate on the issue of stored procs vs. paramaterized, in-line SQL (and I'd welcome input on this debate from people I resepct here)- I don't really have a "side" on the issue. Like most programming issues, I say make the right decisison for the right circumstance. Even if Stored Procs are the way to go, though, I resent my boss making that decision for us- I think i'dt be better if she'd just trusts us to make the right decisions, although she did say she'd not stop us from writing in-line SQL, but I know if there are ever problems she'll blame it on that without ever looking into the problem for real.
At any rate, her reasons for using Stored Procs over in-line SQL? Speed and maintainiability. "Maintainablility" is a funny argument because while Stored Procs are easy to correct and deploy (since they are in the database), they are much more difficult to organize and read, especially if you do all of your CRUD with them (requiring hundreds of Stored Procs). So I don't know that I buy the whole maitainability thing.
What really gets me is the performance thing though. She uses this argument like a trump suite- how can you argue with performance? However, both in-line sql and stored procs are compiled the first time they are executed and the only performance gain you get from a stored proc has to do with the way it is looked up for subsqent executions (both are cached, but apparently stored procs are cached in a little easier to find place). This time savings is going to be imperceptable to a user pressing a button, but for her it is the knock-out argument. Now I'll totally agree if it is a call that is going to be made thousands of times in a loop where the time can add up, but if it is a simple request in response to a use pressing a button, I think there are far more important concerns than the nanoseconds that might be saved that are impossible for the user to perceive. Things like true matinatability, code readability, good abstraction, etc.
Anyway, I'm tired of people trying using knock-out blows for any coding concept (not anyone here, BTW, just the trend I've seen and participated in in the past). Use the right tool in the right situation. We are not all writing the same apps, therefore we all have different goals at different times. A database application is very different from a 3D graphics engine is very different from a compiler is very different from a . . .
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267294 - 17/10/2005 09:53
Re: Humor For Programmers
[Re: JeffS]
|
addict
Registered: 24/07/2002
Posts: 618
Loc: South London
|
Quote: Consider the following code: Code:
for (i=0; i<Accounts.Count; i++) { Accounts[i].Process(); }
This seems farily straightfoward code, so a comment like "//Loop through our accounts and process them" is not useful. We can see that from the code. However, a comment telling us what the real-world problem is that we're trying to solve is helpful in understanding the bigger picture: "//Calculate new monthly values for each of our accounts based on current market values".
But I wouldn't be calling the member function "process", I'd be naming it after what it does, therefore a comment wouldn't give me anymore information than what the line of code does! :P
|
Top
|
|
|
|
#267295 - 17/10/2005 11:40
Re: Humor For Programmers
[Re: JeffS]
|
pooh-bah
Registered: 09/08/2000
Posts: 2091
Loc: Edinburgh, Scotland
|
All the apps I like to see use stored procs, but my requirements are not performance based, but security based, and it is much easier to meet FSA requirements with a limited set of stored procedures. It is so common to see an app which appears secure at first glance but is vulnerable to a simple SQL Injection atack, thus rendering all the front end security laughable.
<sigh>
_________________________
Rory MkIIa, blue lit buttons, memory upgrade, 1Tb in Subaru Forester STi MkII, 240Gb in Mark Lord dock MkII, 80Gb SSD in dock
|
Top
|
|
|
|
#267296 - 17/10/2005 11:45
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 19/01/2002
Posts: 3584
Loc: Columbus, OH
|
Quote: But I wouldn't be calling the member function "process", I'd be naming it after what it does, therefore a comment wouldn't give me anymore information than what the line of code does! :P
hmm...
Accounts[i].calculateNewMonthlyValueForOurAccountBasedOnCurrentMarketValue();
seems a bit verbose...
_________________________
~ John
|
Top
|
|
|
|
#267297 - 17/10/2005 11:53
Re: Humor For Programmers
[Re: JBjorgen]
|
carpal tunnel
Registered: 18/01/2000
Posts: 5683
Loc: London, UK
|
Quote: hmm...
Accounts[i].calculateNewMonthlyValueForOurAccountBasedOnCurrentMarketValue();
seems a bit verbose...
So? That's what Intellisense (or whatever it's called in your favourite IDE) is for.
_________________________
-- roger
|
Top
|
|
|
|
#267298 - 17/10/2005 18:41
Re: Humor For Programmers
[Re: Roger]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
Quote:
Quote: hmm...
Code:
Accounts[/i].calculateNewMonthlyValueForOurAccountBasedOnCurrentMarketValue();
seems a bit verbose...
So? That's what Intellisense (or whatever it's called in your favourite IDE) is for.
Intellisense might help you write it, but understanding it's a different story. I personaly think the comment is easier to read, but to each his/her own.
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267299 - 17/10/2005 18:48
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
Quote: But I wouldn't be calling the member function "process", I'd be naming it after what it does, therefore a comment wouldn't give me anymore information than what the line of code does! :P
1. See John's Post
2. Sometimes you don't get any control over what the functions you're calling are named, especially if you're using generic utilities.
3."Process", in the real world from which I took this example (it isn't real code, but it is a real concept), is the right name for what is happening to the account- that's what the users call it. In fact, the button they push is called "process". So it's not as generic as it sounds. However, if I leave it at that then any programmer wanting to know more about what the code is trying to accomplish has to go to external documentation and read about what "monthly processing" is. I'd rather give an overall description right in the method so anyone coming behidn me (including myself) can follow my train of thought.
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267300 - 17/10/2005 18:54
Re: Humor For Programmers
[Re: frog51]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
Quote: All the apps I like to see use stored procs, but my requirements are not performance based, but security based, and it is much easier to meet FSA requirements with a limited set of stored procedures.
I can see that, and it's a good point. Our users are all internal to the company, so security isn't AS big of a deal. Still, it's an important consideration since no project stays confined to the rules under which it was initially developed, especially with regards to security.
Quote: It is so common to see an app which appears secure at first glance but is vulnerable to a simple SQL Injection atack, thus rendering all the front end security laughable.
I would like to point out that I was referring to paramaterized in-line SQL, which is not vulnerable to SQL Injection attacks (not that any one who has access to these systems would know what a SQL Injection attack is). I do realize, however, that SQL Injection is not the only security concern that Stored Procs address. They can really allow you to lock down all access and tightly control what is being done to the data.
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267301 - 18/10/2005 03:48
Re: Humor For Programmers
[Re: JeffS]
|
carpal tunnel
Registered: 13/02/2002
Posts: 3212
Loc: Portland, OR
|
Quote: I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.
This is soooo important. One of my functions at work is to review code written by the rest of our department members. I can't count the number of times that I've seen code that makes me go "huh?" -- the code may be "self-documenting", but not doing what I think it should be doing. The first question I'll usually ask is "why are you doing this?" Sometimes the answer is "well, I tried doing it this [what I would have expected them to do], but it had a problem that doing it this way avoids," to which I'll say "Maybe you could add a comment to that effect, so that whoever maintains this code after you doesn't waste time by ripping it out, and trying to replace it with that." Sometimes I just get a shrug, or an answer that isn't very well thought out -- those are the cases that tell me that a) the developer didn't spend much time thinking about the design, or b) the developer doesn't know the language well enough to know a better way to do it, or c) the code is probably buggy. I've caught a lot of buggy code as a result.
Further, "self-documented code" is sometimes just wrong -- you start out with a function named one thing, which then gets minorly modified so that it subltly doesn't quite live up to its name, but no-one changes the name of the function, because it's an API, and you don't know who else is using the function. Personally, I've never seen any non-trivial so-called "self-documented" code where the "self-documenting" is as complete as it needed to be.
If your comments tell the WHY, and your code tells the HOW, it's a lot easier to make sure that the HOW is actually correct.
On a related note going back to Paul's original comment about incomplete documentation, which spawned this subthread: "documentation" isn't just "commenting code". Documentation encompasses a whole lot more than that, from design specs, to commenting code (algorithms, data structures, code components, etc) to writing end-user documentation.
|
Top
|
|
|
|
#267302 - 18/10/2005 05:26
Re: Humor For Programmers
[Re: canuckInOR]
|
addict
Registered: 24/07/2002
Posts: 618
Loc: South London
|
Quote:
Quote: I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.
This is soooo important. One of my functions at work is to review code written by the rest of our department members. I can't count the number of times that I've seen code that makes me go "huh?" -- the code may be "self-documenting", but not doing what I think it should be doing. The first question I'll usually ask is "why are you doing this?" Sometimes the answer is "well, I tried doing it this [what I would have expected them to do], but it had a problem that doing it this way avoids," to which I'll say "Maybe you could add a comment to that effect, so that whoever maintains this code after you doesn't waste time by ripping it out, and trying to replace it with that." Sometimes I just get a shrug, or an answer that isn't very well thought out -- those are the cases that tell me that a) the developer didn't spend much time thinking about the design, or b) the developer doesn't know the language well enough to know a better way to do it, or c) the code is probably buggy. I've caught a lot of buggy code as a result. [/QUOTE]
Which is exactly the case andy mentioned above and what I was inferring, sometimes things have to be done oddly and not in the way you would necessarilly think or want to write them. In those cases a single line comment saying "It's done like this because " will suffice.
Quote: Further, "self-documented code" is sometimes just wrong -- you start out with a function named one thing, which then gets minorly modified so that it subltly doesn't quite live up to its name, but no-one changes the name of the function, because it's an API, and you don't know who else is using the function. Personally, I've never seen any non-trivial so-called "self-documented" code where the "self-documenting" is as complete as it needed to be.
The name of the function might lie, but the code inside it wont. I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!
Dunno, maybe I'm odd, maybe my CAD field (ultra fast database with ultra fast graphics) is so far removed from "data entry" style software.
Edited by sn00p (18/10/2005 05:29)
|
Top
|
|
|
|
#267303 - 18/10/2005 09:47
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 14/01/2002
Posts: 2858
Loc: Atlanta, GA
|
On a side note to all of this commenting stuff, one other thing I use comments for is refactoring or rewriting code. Whenever I have to maintain an app that was not developed well, has no external documentation, is not self-documenting, and is not commented well (which describes every app I've been hired to maintain), whenever I have to work in a certain module the first thing I do is go in and start commenting the code. This forces me to take the time to understand the mess step by step, and since it's easy to get overwhelmed by 1500 line methods that do 100 different things with no comments, it keeps me on track. Certainly there are other ways to understand code, but that really works well for me personally.
"If you can't describe it, you can't code it or maintain it," is probably my mantra and the reason I'm so hot on using comments. Of course, I realize that there are other was to display understanding besides being able to write comments, but that is a nice litmus test I use on myself.
_________________________
-Jeff Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.
|
Top
|
|
|
|
#267304 - 19/10/2005 19:59
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 13/02/2002
Posts: 3212
Loc: Portland, OR
|
Quote:
Quote: Further, "self-documented code" is sometimes just wrong -- you start out with a function named one thing, which then gets minorly modified so that it subltly doesn't quite live up to its name, but no-one changes the name of the function, because it's an API, and you don't know who else is using the function. Personally, I've never seen any non-trivial so-called "self-documented" code where the "self-documenting" is as complete as it needed to be.
The name of the function might lie, but the code inside it wont.
Now, suppose there's a bug in the code, so that it's doing something yet even more different -- you have a function named for something it's not really doing, the original programmer's intent is to do something that the code's not actually doing -- without a comment explaining what the intent was, are you, the maintainer, going to guess at the code's intent, or just incorrectly fix it to do what the name of the function is?
Quote: I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!
That's partly why it's so important -- if the comments match the code, then you know it's more likely things are hunky-dory. If the comments don't match the code, then you and the developer need to have a chat, because it's an indicator that he didn't write what he intended to write.
In addition, tons of research has been done that shows commenting code does improve maintainability and code readability. Welcome to the field of software metrics analysis. Several years ago, I spent 8 months as an intern with a the Software Engineering and Analysis Lab at Nortel (I can't find an external web-presence for them, but there's an description for them here).
Lots of statistics; I couldn't hack it, and had to get out.
In general, I treat blocks of code as a paragraph, and, just like paragraphs have an introductory sentence, I typically add a summary comment about what the block of code is supposed to be doing, and why. Line-by-line commenting is excessive, and metrics analysis shows that too much commenting can be just as bad as too little.
|
Top
|
|
|
|
#267305 - 19/10/2005 20:40
Re: Humor For Programmers
[Re: canuckInOR]
|
carpal tunnel
Registered: 24/12/2001
Posts: 5528
|
It is all a balance. You need a concise function name and a concise set of comments. Just because the compiler gives you the ability to have a 255 char long function name doesn't mean you should have an insanely long function which describes exactly what it does. You shouldn't put a comment in for every single line either. What's next on the discussion list? Vi or Emacs? Code formatting style? OS distribution? ![](/ubbthreads/images/graemlins/wink.gif)
|
Top
|
|
|
|
#267306 - 19/10/2005 20:42
Re: Humor For Programmers
[Re: sn00p]
|
carpal tunnel
Registered: 24/12/2001
Posts: 5528
|
Quote: The name of the function might lie, but the code inside it wont. I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!
Eww! A bad comment or an incorrect function name is actually worse than a function with no comments and a vague function name. If you're not going to bother keeping stuff accurate then you might as well rip it out to save confusion.
|
Top
|
|
|
|
|
|