I'm just pointing out that it's in our best interest to allow the code to document as much as absolutely possible.
Absolutely.
Nothing beats good code. Given that sometimes there is bad code, it would be better if the code contained documentation - that's my position.
I'm also pointing out that no documentation is many times better than incorrect documentation
That's an absolute statement which I think you don't really mean. For instance:
// this algorithm comes from page 293 of the book "Numerical Recipies in C"
Well, what if the algorithm actually came from page 294? The documentation is incorrect. But even that HINT of the source of an algorithm is SO MUCH BETTER than no documentation at all, that it's killing me that people are disagreeing with me on this point! =)
I agree, we're both coming awfully close to making absolute statements - to which there are always exceptions. But I'd rather have the hint of the coder's state of mind (even if they do a crappy job of explaining themself), than no hint at all - when faced with code which is provably misbehaving. *shrug* Especially since I can always just keep hitting that "del" key to make their bad comments disappear, but the only thing I can do to make comments appear is figure out the intended behavior of their damned code, and type it in, myself. Which can be pretty tough, sometimes - I've seen some Grade-A Horseshit code, in my day. *shrug*
It likely would have to be expanded to include error checking if the item wasn't found.
That task would either have to be performed by the original coder, or by someone else. In either case, documentation would help. Something along the lines of:
// TODO : error check if it can't find a person named Harry.
Wouldn't you agree?
Assume that the list is unique.
Well, that would be a good thing to document, now, wouldn't it? Otherwise, when a new coder comes in, they'll be all paranoid about the possible existence of other People with the same first name. And if the requirements of your program change to encompass the possibility of multiple People with the same name, wouldn't it be good to have a comment along the lines of:
// ASSUMPTION: assumes uniqueness of Person
Granted, your code could be bloated to actually test all of these conditions in each use case - but I'm just asking for comments at the top of the Person class, for instance. I think it would be more useful to document in each function that you're making such an assumption.
And indeed you shouldn't know how.
I agree with another poster that you could potentially overload each function that takes a string to take both a string and a wstring, for instance, in order to handle Unicode input. What I was actually suggesting was that it would be better to call your function like this:
Person::findPerson(L"Harry")
Of course, this is C++ and therefore would return a std::string as all C++ programs should.
Actually, I would argue that your function should return either a "const std::string&" or a "const std::wstring&", so that it's clear that you can't modify the output, and so that less useless byte-copying is performed. Granted, string is pretty light-weight, but it's a good coding practice to get into.
Again though, how would commenting help this?
Doing away with comments doesn't magically make existing code better. Many people have argued with me - saying that adding comments does make code worse. I think they're crazy. Code will always have mistakes, but documentation gives you insight into the mind of the coder like code cannot. Especially when you see something like "// FIX THIS" sprinkled around. =)
This only goes to prove my point that properly written code doesn't need commenting.
I would argue that by your definitions the only "properly written code" would be code that meets at least one of these two criteria:
It was written by someone with total recall. (In other words, they could recall the initial requirements perfectly, and had no need to write them down for posterity.)
It can be proven to contain no bugs.
Since neither criteria is very common, I would argue that almost no code is "properly written". I use your initial snippet as an example. Even something as simple as that had, in my mind, many problems. And you even agreed with one of my complaints! Therefore, your code was not properly written! COMMENT IT!
It also reenforces the idea that commenting may lead to laziness on the part of symbol naming.
Bad habits will always exist. One good habit is documenting unfinished code. Another good habit is documenting the design of any code, and the expected results under outlier conditions.
Your assuming that the container is not unique. That is a bad assumption.
If you'd documented your code better, I would have realized that. That sounds like a communication problem between two coders. One way to address that (not "solve", but "address") is that each coder try to document their assumptions, where it makes sense to do so. "At least once" would be nice.
Constants are only good if they are going to be used multiple times and represent some abstract concept.
Or, if their value ever needs to be changed in the future. (Such as making it Unicode compliant.) Or if the existence of the constant itself needs to be documented. Or if the constant itself comes from an original source, such as a paper describing an algorithm, or requirements specifications. Or if the constant needs to be translated into multiple languages. Or if the behavior of the constant needs to be checked by regression tests. I could go on, but I think that I've shown that your statement was rubbish.
There are a certain set of variables reserved for local semi-anonymous operations.
Who reserves them? Oh, you do. What about every other coder who'll have to look at your code? Do they get reserved variables, too?
If you've ever written code like this:
for (int i=0; i<max_i; i++) {... }... for (i=0; i<max_i; i++) {... }
Then you're guilty of writing non-portable code. The variable "i" is neither reserved by the compiler, nor do all compilers check to make sure that "i" is properly in scope in the same manner.
...since it is obvious that the variable isn't important.
I believe you meant to say "since it is obvious that the variable name isn't important."
I kind of like the rule that the length of a variable name should be proportional to the log of the length of its scope. *shrug* I know what you're getting at, but you must agree that as soon as the usage conditions on "p" become greater, it should probably be renamed. *shrug* Not really one of my main arguments.
Why must we always write code to be indestructable by a "new coder"?
Good code is a journey, not a destination. I think everyone should at least make an attempt to constantly improve their technique. If I didn't care what other people think or do, I wouldn't bother to argue with you.
The code is the behavior its SUPPOSED to have.
Wait just a minute. Let me go back and quote you to you, again:
It likely would have expanded to included error checking if the item wasn't found.
Well, WHICH IS IT? That code was either SUPPOSED to crash, if the item wasn't found, or it "likely would have to be expanded to include error checking."
This really pisses me off. Can't you see how dumb you sound, here? I know that you're an intelligent person - you're making pretty good arguments - they just happen to be incorrect. But these two statements here, more than anything else, prove that your argument contains inconsistencies.
The maintainability nightmare arrises when there are two sources of behavior
Let me list sources of behavior:
What the user thinks they want
What the user really does want
How the conditions will change in the future
How the coder meant to type in the code (typing in an algorithm it's possible to have typos - it's VERY useful to CITE your sources, so they can be checked, later. Otherwise, I have to figure out, by hand, what's wrong with the code you typed in.)
Since there are always multiple "sources of behavior", I think it would be far better to document the choices that the coder made, than to leave them up in the air, undocumented.
Comments are inferior to code
Code without comments is inferior to code with comments.
Granted, I'm expecting a certain level of maturity in the people writing the comments, but your assertion seems to be that the code is somehow BETTER if you intentionally REMOVE intelligent comments. That is an untenable position.
I disagree with your summation of "the real problem", in your parting paragraph.
I think "the real problem" is that it's impossible for the computer to understand the intention of a coder. It is only possible to verify the intended behavior of code, by having another human read the code. That process is aided by good documentation. I agree with your assertion that bad documentation is misleading. However, code with documentation is guaranteed to be AT LEAST AS GOOD as code without documentation. It is always possible for a human to remove documentation, and look at just code. At the very least, cite your sources for algorithms that you implement - that alone would dramatically improve the quality of a lot of code.
Six times* in your comments, you argue for the existence of documentation beyond the mere existence of the code. In the context of the debate, there were two positions:
Documentation is worthless.
Documentation is valuable.
I agree that there are many more layers to the debate, but each of the arguments you have made implies the existence of SOME documentation. Can't you see that you're on my side? It's not much of a debate, if you agree with me. =)
I'm not saying that I have the solution to everything, but I do know one thing for a certainty:
The worst of all possible solutions is no documentation, at all. (Excluding the consideration of "code as document".)
I don't believe you disagree with my statement. If you do, feel free to phrase your retort for maximum effect.
* Here are the six times (with emphasis added) you referenced the existence of documentation, beyond just the code.
Anywhere that the code does not "document" the program, the progammer needs to provide explicit documentation or write clearer code. (Self explanatory case.)
In your second case, you essentially argued the case for a revision control system, with strong documentation, and regression tests. I would argue that, being external to the actual functioning of the code, that regression tests qualify as additional documentation. I particularly feel that regression test code should contain high-level documentation in the form of comments - specifically, when the tests can cite design documents or requirement specifications.
Nonetheless, it's is definitely necessary to document particulary nasty chunks of code, but keep the documentation at the highest level possible. (Again, fairly self-explanatory case.)
If it is a system overview comment, it belongs in a design doc. (A design doc is written primarily not in code.)
If it describes how a black box *should* work, it belongs at the highest level of that box (ie, class or function). (I believe "it" referred to documentation beyond the code.)
If it is a single line genius piece of code, by all means, document it.(Self explanatory.)
Your post is not really relevant to what we were discussing, as we were not directly discussing Leo.
I was asserting that documentation is good and necessary, in response to the other poster saying that documentation is never necessary. I don't really think that "inline or not" comes close to describing what we were debating.
I agree with you that I overstated. But I disagree with you that overloading on classes solves the general case problem. For instance, if I want to find everyone who was hired before a certain date, overloading find on some "HiredBeforeDate" class is pretty absurd.
I think using functors is a much better approach. Wouldn't you agree?
If a Person has two attributes with the same type, function overloading doesn't help you document behavior at all. You still need to name the attribute you're looking for.
I don't know if Person::find("June 26, 1975") is looking for date of birth, or date of death, date of marriage, date of hire, etc.
"even the ones that really should be defined at the function definition"
Keep in mind, this poster thought that NOTHING (not even function definitions) needs documentation.
If your argument is that documentation is worthless, then make your case. I'm not really that interested in the original code. I'd rather debate the topic at hand. What was offered was a concrete example - so I tried to knock it down.
Even if you resolve all of my complaints, though, I think the intended behavior of the code is still unclear, without documentation.
The argument was made that good code is self-documenting. I'm saying that good code only documents its own current behavior.
What is completely lacking is any indication of what should happen, as soon as the use cases become more complicated.
The original poster was implying that the code was so perfect, that everyone should shut up and worship it as the end-all, be-all of self-documenting code. I found many, many flaws with the code. If you want to write the perfect version of it, that meets all of my demands, go for it.
But - every time I add NEW requirements, you'll have to massively modify the code. As the code becomes more and more complex, it will have more opportunities to gain bugs. All this while, though, the documentation might remain constant, if it's written clearly enough.
*shrug* You're welcome to your opinion, but I'd appreciate it if you wouldn't post as an Anonymous Coward, so I could have a real debate with you.
*shrug* I was trying to knock the wind out of the implied argument that the code was so simple, there's no reason for anyone to complain.
So, I complained.
As to your point, yes - documentation on an API is far more valuable than documentation in the usage of an API. But, I think I've made it clear that the intended behavior of that code was not at all clear.
its too hard to update comments when you are updating code,
I think you're the one who needs to find a different job. If your argument is that the benefits of updating comments are far outweighed by the costs, then make that argument. Don't whine about "too hard".
if you have a code that has a chain of things to be changed for it to work right... you will end up breaking your thought process if you update the comments while updating the code;
Fine - update the comments immediately after you update the code. Your thought process isn't interrupted, changing the comments isn't really all that hard, and you're left with good documentation that you can use as the basis of your work, the next time there's a problem in the code.
however if you do not update the comments a month or year later when it is used again and needs to be changed someone will have to go though a massive debugging because they beleive the comment is correct
That's why I think you should update the comments. You seem to be switching sides in your argument, here.
problems like that happen a lot when you comment a large project, which is why in the long run it is easier to just not comment, in the short term as well.
There turns out to be no actual logical argument to what you've said. Your argument boils down to two points: it's hard to modify the documentation, and bad documentation is misleading. Well, it's not hard to modify the documentation, and bad (or no) documentation IS misleading - that's why coders should put effort into creating and maintaining good documentation.
I will offer several points as the converse to your arguments: it's far easier to document code immediately after writing it than it is to document it several months down the line - and it's very hard to understand the INTENDED behavior of bad code without any documentation.
I can't tell what your code should do if it can't find a person named Harry.
I can't tell what your code should do if it finds multiple people named Harry.
I can't tell how to use your code to find a person whose name requires Unicode to represent it.
I can't tell if.name returns a char * that I'm supposed to free or delete [], if it returns a const char *, if it returns a string that I can modify but won't modify the original Person, if it returns a string reference which I can use to modify the original Person's name, if it returns a wstring reference which I can use to modify the original Person's name, if it returns a const string reference, or if it returns a const wstring reference, or if it uses some other string representation like a Qt one, or some custom one - heck, it could even use an MFC-style CString.
I don't like that the function you've called is named "findPerson" - wouldn't it be far better to call it something like "findPersonByFirstName"? Or "findFirstPersonWithFirstName"? For that matter, why am I calling "Person::findPerson"? Isn't that slightly redundant? Wouldn't "Person::find" be just as clear, and less verbose? Therefore, the function should be something like "Person::findFirstWithFirstName". Wouldn't that be much more highly documented than what you've got?
While we're on it, if it is returning the "first", by which method is it sorted? Shouldn't I be able to pass in a parameter which describes the order in which I want the results returned? And shouldn't you get an iterator instead of a reference, anyway?
Back to "name", is that their entire given name? Is it a nickname? Is it in last-name first format? Is there some additional identifier in the name if two people have the same name?
And I still don't know if I'll get a special Person which is supposed to be a Non-Person, if it can't find "Harry", or if this is going to throw an exception.
I don't like that your code uses a hard coded-value, "Harry".
I don't like that your code has the variable "p". Granted, you've got a pretty amazingly short scope in your example, but code tends to grow. It would be better if the variable had a slightly longer name.
There are all sorts of things to nit-pick about, that a new coder could be confused about, or bugs which might be on the verge of instantiation, even in code as simple as yours.
But my real point is this:
If I've just walked in to your code, I don't know what behavior it's SUPPOSED to have, since you haven't documented that. All I can tell is what it DOES do. And since code changes over time, it's impossible for me to distinguish between the two, unless you document it.
It helps if when you translate it to make it stick to the standard, you do it correctly:
void swap(int& A, int& B) {
A ^= B;
B ^= A;
A ^= B; }
It's an XOR-equals at the end, not an AND-equals.
Also, yes, if you intentionally pass by reference the same exact integer twice, it's not going to work. It will, however, work if you test it appropriately with:
void f() {
int a = 3;
int b = 3;
swap(a, b);
cout a " and " b endl; }
The test that the other poster inserted of (A == B) is only necessary if you pass in by reference the same int twice. Passing two ints that happen to have the same value works just fine.
So, the function will act as advertised - it will exchange the values of two integers, without using any additional memory.
Why not? You have to do a full-screen capture. Then, you can do a diff against the last full-screen capture, and send the delta. The delta is going to be tiny the vast majority, most of the time.
But, if the damned card is reading back at 8 frames per second, you've got 0.125 seconds latency. Period. No escaping that.
You practice basic algebra to learn what a number is.
You practice trigonometry to learn basic algebra.
You practice calculus to learn trigonometry.
You practice statistics to learn that statisticians lie.
All kidding aside, you do kids a disservice when you expect less from them. The problem isn't that kids can't learn - it's that they have no reason to believe that learning does them good, no tools to learn things that are challenging, and an environment that makes learning harder than it should be.
We spend way too much time worrying about leaving behind the half of the bell curve under 100 IQ, and nowhere near enough time worrying about boring the hell out of the half of the bell curve over 100 IQ.
We need to seriously rethink how we value education in general, and educators in particular.
Your arguments all seem to boil down to your last point - that it's not worth it, based on the extra revenue that the development would generate. That's really not for you or me to decide. All that we can do is to try to prop up a good use case, and hope that some vendors will listen.
I'm defending the use case, and you're attacking it. Why do you care? If your argument is that it's not "reasonable" to expect them to support it, based on the additional money they would make, that's fine - I don't necessarily disagree with your opinion about that.
What I'm saying is that there's both a need, and a simple software solution. The vendors would do good to encourage this kind of feedback - it makes their products better.
I'm saying that it makes sense, at any given moment, to take advantage of the bandwidth that's there. If I render a scene, I expect that to be fast. If I then pause until I can capture the image back to main memory, I expect that to be fast, as well. 8 frames per second is agonizingly slow. In the case of near real-time, waiting 0.125 seconds for a screen capture is very frustrating. Especially when you can render the frame in something like 0.0125 seconds. It's not as though the AGP bus is doing both tasks at the exact same instant, as you seem to keep implying.
Intranet: So, because the article didn't mention something, I can't mention it, and it's not worthy of your contemplation? What? =)
In this specific use case, every vendor has crappy drivers. If you've got a better list of what their driver developers should be working on, by all means, post it. Until then, let them work on the reported issues and requested features - this sounds like a good one, to me.
First, 10-r, 10-g, 10-b is pretty valuable to some people. I agree that 2-bit alpha is pretty miserable - but some people don't need to alpha blend. *shrug* I was just illustrating that there are color schemes in shipping products today, that use more than 24 bits for rgb.
Second, for those people that DO need to blend, they often need to blend 100s of images. You don't need to get out to 1000s of images to see these effects. Just because current standards for MPEG and JPEG don't allow more, that doesn't mean it's useless. And I'm talking more about generating PRman (RenderMan)-style graphics. One approach is to render many, many passes - decomposing the math down into 100s (1000s) of images. It adds up to visual artifacts, very quickly, unless you have extended bit depths.
Third, saying the first poster was posting flamebait - I was saying that what you were doing was a case of "the pot calling the kettle black." I was accusing you of posting flamebait. =)
First, Matrox and 3dLabs are both shipping products that do 10r-10g-10b-2alpha color.
Second, the poster wants to do more than "make due". You can also make due with 16 colors. And no, 256 levels is not enough, if you're compositing many images together, or if your data has a high dynamic range (which would require more gamma range than 256 levels are capable of providing, without serious banding.)
"the idea of transferring back rendered images over the AGP bus for TV / film / etc. is a joke..."
Why? You don't seem to follow up this opinion with any facts to back yourself up. Being able to do things like Interactive Multi-Pass Programmable Shading means that you can achieve near-PRman levels of graphics quality, using standard graphics hardware. But, of course, you need to capture that back to main memory for it to be any use. That hardly seems worthy of your ridicule.
"as someone else pointed out, transferring back high-res images would take up over 200MB - that's a quarter of your AGP bandwidth!"
Who are you to decide what's a good use case, and what's a bad one? This sounds to me like a case where several different people have presented reasonable requests for features - and you're shooting them down because you think what they want to do is "a joke". Since this can be fixed with a software update, I think it's a pretty reasonable request.
"you simple couldn't realise the full potential of the bandwidth without a lot of other (expensive?) hardware..."
Why on earth do you make that claim? Could you back that up with some facts? The article is claiming that it's a software issue, only. In fact, the test they put together sounds like a very reasonable one - they're not coming anywhere NEAR using the bandwidth in creating the images, and still, they're getting horrible bandwidth, downloading them. That doesn't sound like contention and timing - that simply sounds like bad, bad drivers.
"you would be *far* better off taking a stream of data from the DVI connector"
So, now, to solve the bandwidth issue, you're going to add a second card to the motherboard. What magical, ethereal bus bandwidth will this second card use? I think you need to re-examine your argument on this point.
"However when does that require 3d rendering to be taking place?"
This isn't just talking about 3d rendering. This is all screen capturing.
"There should be no contention and no reason why the AGP bus couldn't be utilised fully"
Wait a minute - now you're switching your argument?
"would the graphics companies make enough out of this to justify the effort?"
As everyone keeps saying, this sounds like it can be fixed in software. That's a pretty negligible cost for the vendors to spend.
"As for internet streaming - how many people have access to bandwidth fast enough for high quality, full screen video streaming?"
What about intranet? Lots of companies have intranet bandwidth fast enough for what you're talking about.
If I'm reading the article correctly, they're claiming that you can barely get 30 frames per second, full-screen. If you want to do a diff, and send the delta, you potentially need to be able to capture the full screen to do it. If you can only capture at 30 frames per second, you are LOCKED at 30 frames per second, even if you try to compress the output, and send only deltas.
If you're doing multi-pass rendering, it might be extremely convenient to capture the results back to main memory. Especially if the board doesn't have enough texture memory to support all of your temporary buffers.
And boards are starting to ship with 128-bit IEEE floating point buffers.
Essentially, you're right - a human can't tell the difference beyond 24-bit on a given image. But if 100 images were composited together (very likely, to support something like RenderMan-style rendering in hardware), 24 bits is nowhere near enough - you'd get all sorts of accumulation error.
Slashdot Mirror
Absolutely.
Nothing beats good code. Given that sometimes there is bad code, it would be better if the code contained documentation - that's my position.
I'm also pointing out that no documentation is many times better than incorrect documentation
That's an absolute statement which I think you don't really mean. For instance:
// this algorithm comes from page 293 of the book "Numerical Recipies in C"
Well, what if the algorithm actually came from page 294? The documentation is incorrect. But even that HINT of the source of an algorithm is SO MUCH BETTER than no documentation at all, that it's killing me that people are disagreeing with me on this point! =)
I agree, we're both coming awfully close to making absolute statements - to which there are always exceptions. But I'd rather have the hint of the coder's state of mind (even if they do a crappy job of explaining themself), than no hint at all - when faced with code which is provably misbehaving. *shrug* Especially since I can always just keep hitting that "del" key to make their bad comments disappear, but the only thing I can do to make comments appear is figure out the intended behavior of their damned code, and type it in, myself. Which can be pretty tough, sometimes - I've seen some Grade-A Horseshit code, in my day. *shrug*
That task would either have to be performed by the original coder, or by someone else. In either case, documentation would help. Something along the lines of:
// TODO : error check if it can't find a person named Harry.
Wouldn't you agree?
Assume that the list is unique.
Well, that would be a good thing to document, now, wouldn't it? Otherwise, when a new coder comes in, they'll be all paranoid about the possible existence of other People with the same first name. And if the requirements of your program change to encompass the possibility of multiple People with the same name, wouldn't it be good to have a comment along the lines of:
// ASSUMPTION: assumes uniqueness of Person
Granted, your code could be bloated to actually test all of these conditions in each use case - but I'm just asking for comments at the top of the Person class, for instance. I think it would be more useful to document in each function that you're making such an assumption.
And indeed you shouldn't know how.
I agree with another poster that you could potentially overload each function that takes a string to take both a string and a wstring, for instance, in order to handle Unicode input. What I was actually suggesting was that it would be better to call your function like this:
Person::findPerson(L"Harry")
Of course, this is C++ and therefore would return a std::string as all C++ programs should.
Actually, I would argue that your function should return either a "const std::string&" or a "const std::wstring&", so that it's clear that you can't modify the output, and so that less useless byte-copying is performed. Granted, string is pretty light-weight, but it's a good coding practice to get into.
Again though, how would commenting help this?
Doing away with comments doesn't magically make existing code better. Many people have argued with me - saying that adding comments does make code worse. I think they're crazy. Code will always have mistakes, but documentation gives you insight into the mind of the coder like code cannot. Especially when you see something like "// FIX THIS" sprinkled around. =)
This only goes to prove my point that properly written code doesn't need commenting.
I would argue that by your definitions the only "properly written code" would be code that meets at least one of these two criteria:
- It was written by someone with total recall. (In other words, they could recall the initial requirements perfectly, and had no need to write them down for posterity.)
- It can be proven to contain no bugs.
Since neither criteria is very common, I would argue that almost no code is "properly written". I use your initial snippet as an example. Even something as simple as that had, in my mind, many problems. And you even agreed with one of my complaints! Therefore, your code was not properly written! COMMENT IT!It also reenforces the idea that commenting may lead to laziness on the part of symbol naming.
Bad habits will always exist. One good habit is documenting unfinished code. Another good habit is documenting the design of any code, and the expected results under outlier conditions.
Your assuming that the container is not unique. That is a bad assumption.
If you'd documented your code better, I would have realized that. That sounds like a communication problem between two coders. One way to address that (not "solve", but "address") is that each coder try to document their assumptions, where it makes sense to do so. "At least once" would be nice.
Constants are only good if they are going to be used multiple times and represent some abstract concept.
Or, if their value ever needs to be changed in the future. (Such as making it Unicode compliant.) Or if the existence of the constant itself needs to be documented. Or if the constant itself comes from an original source, such as a paper describing an algorithm, or requirements specifications. Or if the constant needs to be translated into multiple languages. Or if the behavior of the constant needs to be checked by regression tests. I could go on, but I think that I've shown that your statement was rubbish.
There are a certain set of variables reserved for local semi-anonymous operations.
Who reserves them? Oh, you do. What about every other coder who'll have to look at your code? Do they get reserved variables, too?
If you've ever written code like this:
for (int i=0; i<max_i; i++)
{
}
for (i=0; i<max_i; i++)
{
}
Then you're guilty of writing non-portable code. The variable "i" is neither reserved by the compiler, nor do all compilers check to make sure that "i" is properly in scope in the same manner.
I believe you meant to say "since it is obvious that the variable name isn't important."
I kind of like the rule that the length of a variable name should be proportional to the log of the length of its scope. *shrug* I know what you're getting at, but you must agree that as soon as the usage conditions on "p" become greater, it should probably be renamed. *shrug* Not really one of my main arguments.
Why must we always write code to be indestructable by a "new coder"?
Good code is a journey, not a destination. I think everyone should at least make an attempt to constantly improve their technique. If I didn't care what other people think or do, I wouldn't bother to argue with you.
The code is the behavior its SUPPOSED to have.
Wait just a minute. Let me go back and quote you to you, again:
It likely would have expanded to included error checking if the item wasn't found.
Well, WHICH IS IT? That code was either SUPPOSED to crash, if the item wasn't found, or it "likely would have to be expanded to include error checking."
This really pisses me off. Can't you see how dumb you sound, here? I know that you're an intelligent person - you're making pretty good arguments - they just happen to be incorrect. But these two statements here, more than anything else, prove that your argument contains inconsistencies.
The maintainability nightmare arrises when there are two sources of behavior
Let me list sources of behavior:
- What the user thinks they want
- What the user really does want
- How the conditions will change in the future
- How the coder meant to type in the code (typing in an algorithm it's possible to have typos - it's VERY useful to CITE your sources, so they can be checked, later. Otherwise, I have to figure out, by hand, what's wrong with the code you typed in.)
Since there are always multiple "sources of behavior", I think it would be far better to document the choices that the coder made, than to leave them up in the air, undocumented.Comments are inferior to code
Code without comments is inferior to code with comments.
Granted, I'm expecting a certain level of maturity in the people writing the comments, but your assertion seems to be that the code is somehow BETTER if you intentionally REMOVE intelligent comments. That is an untenable position.
I disagree with your summation of "the real problem", in your parting paragraph.
I think "the real problem" is that it's impossible for the computer to understand the intention of a coder. It is only possible to verify the intended behavior of code, by having another human read the code. That process is aided by good documentation. I agree with your assertion that bad documentation is misleading. However, code with documentation is guaranteed to be AT LEAST AS GOOD as code without documentation. It is always possible for a human to remove documentation, and look at just code. At the very least, cite your sources for algorithms that you implement - that alone would dramatically improve the quality of a lot of code.
- Documentation is worthless.
- Documentation is valuable.
I agree that there are many more layers to the debate, but each of the arguments you have made implies the existence of SOME documentation. Can't you see that you're on my side? It's not much of a debate, if you agree with me. =)I'm not saying that I have the solution to everything, but I do know one thing for a certainty:
The worst of all possible solutions is no documentation, at all. (Excluding the consideration of "code as document".)
I don't believe you disagree with my statement. If you do, feel free to phrase your retort for maximum effect.
* Here are the six times (with emphasis added) you referenced the existence of documentation, beyond just the code.
- Anywhere that the code does not "document" the program, the progammer needs to provide explicit documentation or write clearer code. (Self explanatory case.)
- In your second case, you essentially argued the case for a revision control system, with strong documentation, and regression tests. I would argue that, being external to the actual functioning of the code, that regression tests qualify as additional documentation. I particularly feel that regression test code should contain high-level documentation in the form of comments - specifically, when the tests can cite design documents or requirement specifications.
- Nonetheless, it's is definitely necessary to document particulary nasty chunks of code, but keep the documentation at the highest level possible. (Again, fairly self-explanatory case.)
- If it is a system overview comment, it belongs in a design doc. (A design doc is written primarily not in code.)
- If it describes how a black box *should* work, it belongs at the highest level of that box (ie, class or function). (I believe "it" referred to documentation beyond the code.)
- If it is a single line genius piece of code, by all means, document it.(Self explanatory.)
Or did I miss something?Your post is not really relevant to what we were discussing, as we were not directly discussing Leo.
I was asserting that documentation is good and necessary, in response to the other poster saying that documentation is never necessary. I don't really think that "inline or not" comes close to describing what we were debating.
I agree with you that I overstated. But I disagree with you that overloading on classes solves the general case problem. For instance, if I want to find everyone who was hired before a certain date, overloading find on some "HiredBeforeDate" class is pretty absurd.
I think using functors is a much better approach. Wouldn't you agree?
If a Person has two attributes with the same type, function overloading doesn't help you document behavior at all. You still need to name the attribute you're looking for.
I don't know if Person::find("June 26, 1975") is looking for date of birth, or date of death, date of marriage, date of hire, etc.
"even the ones that really should be defined at the function definition"
Keep in mind, this poster thought that NOTHING (not even function definitions) needs documentation.
*shrug*
If your argument is that documentation is worthless, then make your case. I'm not really that interested in the original code. I'd rather debate the topic at hand. What was offered was a concrete example - so I tried to knock it down.
Even if you resolve all of my complaints, though, I think the intended behavior of the code is still unclear, without documentation.
The argument was made that good code is self-documenting. I'm saying that good code only documents its own current behavior.
What is completely lacking is any indication of what should happen, as soon as the use cases become more complicated.
The original poster was implying that the code was so perfect, that everyone should shut up and worship it as the end-all, be-all of self-documenting code. I found many, many flaws with the code. If you want to write the perfect version of it, that meets all of my demands, go for it.
But - every time I add NEW requirements, you'll have to massively modify the code. As the code becomes more and more complex, it will have more opportunities to gain bugs. All this while, though, the documentation might remain constant, if it's written clearly enough.
*shrug* You're welcome to your opinion, but I'd appreciate it if you wouldn't post as an Anonymous Coward, so I could have a real debate with you.
*shrug* I was trying to knock the wind out of the implied argument that the code was so simple, there's no reason for anyone to complain.
So, I complained.
As to your point, yes - documentation on an API is far more valuable than documentation in the usage of an API. But, I think I've made it clear that the intended behavior of that code was not at all clear.
its too hard to update comments when you are updating code,
... you will end up breaking your thought process if you update the comments while updating the code;
I think you're the one who needs to find a different job. If your argument is that the benefits of updating comments are far outweighed by the costs, then make that argument. Don't whine about "too hard".
if you have a code that has a chain of things to be changed for it to work right
Fine - update the comments immediately after you update the code. Your thought process isn't interrupted, changing the comments isn't really all that hard, and you're left with good documentation that you can use as the basis of your work, the next time there's a problem in the code.
however if you do not update the comments a month or year later when it is used again and needs to be changed someone will have to go though a massive debugging because they beleive the comment is correct
That's why I think you should update the comments. You seem to be switching sides in your argument, here.
problems like that happen a lot when you comment a large project, which is why in the long run it is easier to just not comment, in the short term as well.
There turns out to be no actual logical argument to what you've said. Your argument boils down to two points: it's hard to modify the documentation, and bad documentation is misleading. Well, it's not hard to modify the documentation, and bad (or no) documentation IS misleading - that's why coders should put effort into creating and maintaining good documentation.
I will offer several points as the converse to your arguments: it's far easier to document code immediately after writing it than it is to document it several months down the line - and it's very hard to understand the INTENDED behavior of bad code without any documentation.
I can't tell what your code should do if it can't find a person named Harry.
.name returns a char * that I'm supposed to free or delete [], if it returns a const char *, if it returns a string that I can modify but won't modify the original Person, if it returns a string reference which I can use to modify the original Person's name, if it returns a wstring reference which I can use to modify the original Person's name, if it returns a const string reference, or if it returns a const wstring reference, or if it uses some other string representation like a Qt one, or some custom one - heck, it could even use an MFC-style CString.
:
I can't tell what your code should do if it finds multiple people named Harry.
I can't tell how to use your code to find a person whose name requires Unicode to represent it.
I can't tell if
I don't like that the function you've called is named "findPerson" - wouldn't it be far better to call it something like "findPersonByFirstName"? Or "findFirstPersonWithFirstName"? For that matter, why am I calling "Person::findPerson"? Isn't that slightly redundant? Wouldn't "Person::find" be just as clear, and less verbose? Therefore, the function should be something like "Person::findFirstWithFirstName". Wouldn't that be much more highly documented than what you've got?
While we're on it, if it is returning the "first", by which method is it sorted? Shouldn't I be able to pass in a parameter which describes the order in which I want the results returned? And shouldn't you get an iterator instead of a reference, anyway?
Back to "name", is that their entire given name? Is it a nickname? Is it in last-name first format? Is there some additional identifier in the name if two people have the same name?
And I still don't know if I'll get a special Person which is supposed to be a Non-Person, if it can't find "Harry", or if this is going to throw an exception.
I don't like that your code uses a hard coded-value, "Harry".
I don't like that your code has the variable "p". Granted, you've got a pretty amazingly short scope in your example, but code tends to grow. It would be better if the variable had a slightly longer name.
There are all sorts of things to nit-pick about, that a new coder could be confused about, or bugs which might be on the verge of instantiation, even in code as simple as yours.
But my real point is this
If I've just walked in to your code, I don't know what behavior it's SUPPOSED to have, since you haven't documented that. All I can tell is what it DOES do. And since code changes over time, it's impossible for me to distinguish between the two, unless you document it.
"80 MB for ONE texture!"
In a word : no.
- Fraught with uncertainty or doubt; undecided.
- Arousing doubt; doubtful: a dubious distinction.
- Of questionable character: dubious profits.
The search for microbes was dubious, too. Just for instance.If, by your definition, people only attempted "real science" we would never accomplish anything.
What does or doesn't it do?
I'm betting there's a lot of code from the obfuscated code contests that doesn't work on that compiler...
Well, two points :
:
:
It helps if when you translate it to make it stick to the standard, you do it correctly
void swap(int& A, int& B)
{
A ^= B;
B ^= A;
A ^= B;
}
It's an XOR-equals at the end, not an AND-equals.
Also, yes, if you intentionally pass by reference the same exact integer twice, it's not going to work. It will, however, work if you test it appropriately with
void f()
{
int a = 3;
int b = 3;
swap(a, b);
cout a " and " b endl;
}
The test that the other poster inserted of (A == B) is only necessary if you pass in by reference the same int twice. Passing two ints that happen to have the same value works just fine.
So, the function will act as advertised - it will exchange the values of two integers, without using any additional memory.
*shrug* Like anyone cares.
Thanks for playing.
Don't you mean "write"? I can surely "access a variable more than once between sequence points."
I bet it will work on every modern compiler. It's not like I actually think people should use that function. *shrug*
void swap(int&A,int&B){A^=B^=A^=B;}
Short and sweet.
Why not? You have to do a full-screen capture. Then, you can do a diff against the last full-screen capture, and send the delta. The delta is going to be tiny the vast majority, most of the time.
But, if the damned card is reading back at 8 frames per second, you've got 0.125 seconds latency. Period. No escaping that.
*shrug*
You practice basic algebra to learn what a number is.
You practice trigonometry to learn basic algebra.
You practice calculus to learn trigonometry.
You practice statistics to learn that statisticians lie.
All kidding aside, you do kids a disservice when you expect less from them. The problem isn't that kids can't learn - it's that they have no reason to believe that learning does them good, no tools to learn things that are challenging, and an environment that makes learning harder than it should be.
We spend way too much time worrying about leaving behind the half of the bell curve under 100 IQ, and nowhere near enough time worrying about boring the hell out of the half of the bell curve over 100 IQ.
We need to seriously rethink how we value education in general, and educators in particular.
Your arguments all seem to boil down to your last point - that it's not worth it, based on the extra revenue that the development would generate. That's really not for you or me to decide. All that we can do is to try to prop up a good use case, and hope that some vendors will listen.
I'm defending the use case, and you're attacking it. Why do you care? If your argument is that it's not "reasonable" to expect them to support it, based on the additional money they would make, that's fine - I don't necessarily disagree with your opinion about that.
What I'm saying is that there's both a need, and a simple software solution. The vendors would do good to encourage this kind of feedback - it makes their products better.
I'm saying that it makes sense, at any given moment, to take advantage of the bandwidth that's there. If I render a scene, I expect that to be fast. If I then pause until I can capture the image back to main memory, I expect that to be fast, as well. 8 frames per second is agonizingly slow. In the case of near real-time, waiting 0.125 seconds for a screen capture is very frustrating. Especially when you can render the frame in something like 0.0125 seconds. It's not as though the AGP bus is doing both tasks at the exact same instant, as you seem to keep implying.
Intranet: So, because the article didn't mention something, I can't mention it, and it's not worthy of your contemplation? What? =)
In this specific use case, every vendor has crappy drivers. If you've got a better list of what their driver developers should be working on, by all means, post it. Until then, let them work on the reported issues and requested features - this sounds like a good one, to me.
First, 10-r, 10-g, 10-b is pretty valuable to some people. I agree that 2-bit alpha is pretty miserable - but some people don't need to alpha blend. *shrug* I was just illustrating that there are color schemes in shipping products today, that use more than 24 bits for rgb.
Second, for those people that DO need to blend, they often need to blend 100s of images. You don't need to get out to 1000s of images to see these effects. Just because current standards for MPEG and JPEG don't allow more, that doesn't mean it's useless. And I'm talking more about generating PRman (RenderMan)-style graphics. One approach is to render many, many passes - decomposing the math down into 100s (1000s) of images. It adds up to visual artifacts, very quickly, unless you have extended bit depths.
Third, saying the first poster was posting flamebait - I was saying that what you were doing was a case of "the pot calling the kettle black." I was accusing you of posting flamebait. =)
First, Matrox and 3dLabs are both shipping products that do 10r-10g-10b-2alpha color.
Second, the poster wants to do more than "make due". You can also make due with 16 colors. And no, 256 levels is not enough, if you're compositing many images together, or if your data has a high dynamic range (which would require more gamma range than 256 levels are capable of providing, without serious banding.)
Third, pot. Kettle. Black.
"the idea of transferring back rendered images over the AGP bus for TV / film / etc. is a joke..."
Why? You don't seem to follow up this opinion with any facts to back yourself up. Being able to do things like Interactive Multi-Pass Programmable Shading means that you can achieve near-PRman levels of graphics quality, using standard graphics hardware. But, of course, you need to capture that back to main memory for it to be any use. That hardly seems worthy of your ridicule.
"as someone else pointed out, transferring back high-res images would take up over 200MB - that's a quarter of your AGP bandwidth!"
Who are you to decide what's a good use case, and what's a bad one? This sounds to me like a case where several different people have presented reasonable requests for features - and you're shooting them down because you think what they want to do is "a joke". Since this can be fixed with a software update, I think it's a pretty reasonable request.
"you simple couldn't realise the full potential of the bandwidth without a lot of other (expensive?) hardware..."
Why on earth do you make that claim? Could you back that up with some facts? The article is claiming that it's a software issue, only. In fact, the test they put together sounds like a very reasonable one - they're not coming anywhere NEAR using the bandwidth in creating the images, and still, they're getting horrible bandwidth, downloading them. That doesn't sound like contention and timing - that simply sounds like bad, bad drivers.
"you would be *far* better off taking a stream of data from the DVI connector"
So, now, to solve the bandwidth issue, you're going to add a second card to the motherboard. What magical, ethereal bus bandwidth will this second card use? I think you need to re-examine your argument on this point.
"However when does that require 3d rendering to be taking place?"
This isn't just talking about 3d rendering. This is all screen capturing.
"There should be no contention and no reason why the AGP bus couldn't be utilised fully"
Wait a minute - now you're switching your argument?
"would the graphics companies make enough out of this to justify the effort?"
As everyone keeps saying, this sounds like it can be fixed in software. That's a pretty negligible cost for the vendors to spend.
"As for internet streaming - how many people have access to bandwidth fast enough for high quality, full screen video streaming?"
What about intranet? Lots of companies have intranet bandwidth fast enough for what you're talking about.
Enough said...
If I'm reading the article correctly, they're claiming that you can barely get 30 frames per second, full-screen. If you want to do a diff, and send the delta, you potentially need to be able to capture the full screen to do it. If you can only capture at 30 frames per second, you are LOCKED at 30 frames per second, even if you try to compress the output, and send only deltas.
If you're doing multi-pass rendering, it might be extremely convenient to capture the results back to main memory. Especially if the board doesn't have enough texture memory to support all of your temporary buffers.
And boards are starting to ship with 128-bit IEEE floating point buffers.
Essentially, you're right - a human can't tell the difference beyond 24-bit on a given image. But if 100 images were composited together (very likely, to support something like RenderMan-style rendering in hardware), 24 bits is nowhere near enough - you'd get all sorts of accumulation error.