Okay now. I want to get some feedback on some code I wrote, but this means I'm going to have to actually post the code online. In the header of the code you will see a GPL summary type thing saying the code is available under the terms of the GPL, SO: this counts as an official release type thingy, and from this point forward my code can be taken and used and modified by anybody who pleases, yadda yadda yadda. Don't abuse it please, as the code is not done. (You'll see at the bottom of the header the three tasks that need to be completed in the file).
Aaaaanyway, here's the deal: I used some other open-source code elsewhere in my web framework, and I appreciated the level of commenting in it, and tried to duplicate that to make my code developer-friendly, but I think I went way overboard. Fully half of the file is consumed by comments and whitespace. Here's the thing, tho: the majority of the commenting comes in the form of annotations, which are really useful if your IDE looks for that sort of thing (so that you can look up access, parameters, and return types of functions without digging into the file yourself).
Still, when I look at that file, my first reaction is "Jesus Christ, this code is morbidly obese with unnecessary comments".
So what do you think? Should I leave in all the annotations that do no good for the developer looking at the file but help the developer that has included the file for use, or should I cut all that crap out to make the file easier to look at directly?
(lol, I almost posted this without linking the code. Here it is.)
e: lol, with the php extension, my host was interpreting the file and displaying the output, which in the case of this backbone framework file was nothing. I added a .txt extension to fix that.
ee: ok wiseguy, the site insisted on interpreting it if php was in there at all, so now it's just got a plain .txt extension. Just remember that it's supposed to be a .php file.
eee:
JESUS CHRIST. Ok, now I know I did this wrong. I think what I'm gonna do is replace all the annotations on member variables with single line comments describing their purpose.Code:newInputValidator.php (46.8 KB, actual: 41.6 KB) ----------------------------------------------- Number of lines of code: 471 Number of directive lines: 0 Number of empty lines: 88 Number of comment lines: 560 Number of empty comment lines: 381 ------------------------------------------- Total number of lines: 1500 -----------------------------------------------
Bookmarks