I've yet again recieved a review reply that I need more comments. But the review didn't specify what was misleading or exactly what needed to be commented to make things clearer.
This is the kinda crap bad computer science teachers teach entry level computer science students which only leads to them making a bunch of worthless comments which only serve to clutter up source code making them entirely counter-productive.
The only issue with my PriorityQueue demo before(which I have fixed) was that I accidently left a few bits of debug code in which was potentially misleading.
Really the only thing I could have done was stated that my compare function compared numbers for the priority queue and for the two blocks in which I added and removed items I could have stated it with a comment however if it wasn't clear from the simple blocks of code with no function or variables with misleading names then you probably wouldn't be able to get much use out of the library anyway! Though I'm sure if I put in those extra obvious statements it would have been accepted simply because the reviewer saw some grey in the code.
Though don't get me wrong they are preforming a great service for BYOND however I really wish that they wouldn't make vague requirements like that which only serve to get people into poor habits.
Looking over my pathfinding demo there are a few places in which I could put some useful comments though I suspect I'll get whining from the reviewer that the weight of my comments doesn't meet their requirements. Anyway since I'm stubborn as an ass I'm not going to change anything until I'm told what is unclear and needs to be commented. If it never gets accepted it really doesn't matter much to me.
ID:1928
 Jul 9 2005, 3:22 pm
|
|
|
Jul 9 2005, 3:42 pm
|
|
Ol' Yeller
 |
Don't change it, Theo! Stubborness all the way!
|
I personally think you are right.
I think they do this kind of stuff so people can "look through the library and learn about how everything is done"... Ok, I could understand, but it is a library, not a tutorial. If they wanted to learn about all of the gritty code, they could learn it from a tutorial or a demo. Like, I don't quite know how to work with array tables, but I wouldn't expect your pathfinding demo to explain it. With a library, you explain the functions, and explain how to use them. That's it. There shouldn't be any mor eneed for explaination. If you want to explain more, that's great, as long as there is white space, I think it only adds, but it shouldn't be a requirement to over-comment your code. Heh, my java programming teacher was a "bad entry-level programming teacher who makes you over-comment your code" :p If you are such that you can code the stuff, but you can't read minor things and understand them later without comments, then you shouldn't be a programmer. | |
I think the usage documentation on PriorityQueue is a little lacking; it doesn't really do much in the way of explaining what priority queues do to those who aren't familiar with them, for example. On that note, the demo could use a quick one-line description. Yes, anyone capable of using the library sensibly is also going to be capable of reading the code and piecing it together, but that's not the point.
As far as commenting in the guts goes, though, I'd agree wholeheartedly; a function that's 3-6 lines in length generally doesn't need comments all that badly if it has an adequate description written up. | |
When I go browseing for a library I generally already know what I need. Who downloads random libraries without knowing their purpose first? Even a one line description seems overkill for something which just adds 100 items into the queue then takes them out. Though I guess I should elaborate more on the implmentation and effeciency details.
| |
Do you have any sense of curiosity whatsoever? No, I don't just browse library listings at random, and I doubt anyone else does either. But at the same time, if I happen to see an interesting-looking library while looking for something else I usually take a look. Usually the "look" just consists of a glance at the full hub entry, but it is precisely the libraries that I don't know the purpose of that I download for a deeper look at.
| |
I randomly download things from the hub. :P
| |
I was the reviewer, and I'm really sorry for being so unclear.
I didn't mean that you should comment the library part of the code -- I meant that you should comment the demo a little bit more -- especially the PathFinding demo. It would be nice if you could, perhaps, put a one-line description above each demo proc (the library procs are, IMO, already explained very well in the documentation). Though I agree that what each proc does is self-explanatory, a comment about each proc's purpose would be helpful. Also, I agree with Leftley -- that PriorityQueue's documentation could use a little more explanation. If somebody doesn't know what a priority queue is before downloading your library, ideally, after reading your library's documentation, they will. | |
By the way, I see your point about PriorityQueue's demo not needing comments.
(I still think that the PathFinding demo needs them though =P.) | |
When I go browseing for a library I generally already know what I need. I look through the libraries occasionally to see if there's something I could make use of that I wasn't aware of, or something I can learn. It would be a shame to pass by a useful library because there was no description of what it did. I actually don't know what a priority queue is, and for all I know I need one. BYOND is frequently (and perhaps most importantly) used as a learning ground for kids who don't know how to program. I've undervalued that myself in the past, but I try to recognize it more now. I agree that libraries don't really need comments, though they do need thorough API descriptions. | |
