bammerman Posted June 11, 2008 Share Posted June 11, 2008 I work for a company that required a specific comment header on everypage to show incomming and outgoing data, etc... are there any others out there that have to deal with this so called "good coding practice". Could you please post an example because if it is better than the one I am currently using I would love to try to implement it here. Quote Link to comment Share on other sites More sharing options...
ober Posted June 11, 2008 Share Posted June 11, 2008 I would say that's very good GCP. Why do you put it in quotes? That makes it seem like you don't agree. Generally we require class name/author/date created/date updated/inputs/description of methods and what their function is. Quote Link to comment Share on other sites More sharing options...
bammerman Posted June 11, 2008 Author Share Posted June 11, 2008 Oh I totally agree, they are just going overboard. They want every image, link, etc... documented in the header and in the page itself. figured i could find a better way of doing it from my piers here. Quote Link to comment Share on other sites More sharing options...
Darklink Posted June 12, 2008 Share Posted June 12, 2008 Maybe documenting the link and images as owners of them. But documenting everything is practically impossible at times. You should go through a document it as it comes up. Like you would with a function. You would show the name, description and it's paramaters/return values. What is there to document about links and images anyway? "This one goes here..." and "this is a picture of..." would just be silly. Quote Link to comment Share on other sites More sharing options...
bammerman Posted June 12, 2008 Author Share Posted June 12, 2008 What is there to document about links and images anyway? "This one goes here..." and "this is a picture of..." would just be silly. I agree. it isnt that type of documentation it is more Images on this page consist of: <image names> this page is linked to <page names> etc... etc... I think if you know how to code you can read that it is an image file in the code itself. That is why I asked for some examples of the comment headers people use to I can show the bossman that we might be going overboard with the comments. he is a comment nazi i think Quote Link to comment Share on other sites More sharing options...
Darklink Posted June 13, 2008 Share Posted June 13, 2008 Well I don't really document any HTML (a little for CSS but not much) unless I'm debugging templates, in which case comments are generated by the template engine. The things I will comment on is a PHP file itself (header comments including description, version, copyrights, etc). I will comment on functions, classes, object vars, and some details here and there about what is going on and why I'm doing this. If I've added something in for a new version, I may also say so! Here's a small example of how I document. Notice that's clear and it brings out the important parts. Images and links are not really important to link unless a link isn't so obvious. But in that case, one would just go to the link and find out where it goes or what it does. <?php /* ---------------------------------------------- */ // Function description // // @param string example string // @param boolean show string // @return string string to return /* ---------------------------------------------- */ function example($string='', $show=false) { // ------------------------------------- // If show is enabled, echo string // ------------------------------------- if ( $show ) { echo $string; } // ------------------------------------- // Return string to outside world // ------------------------------------- return $string; } ?> Quote Link to comment Share on other sites More sharing options...
GingerRobot Posted June 13, 2008 Share Posted June 13, 2008 Personally i think your commenting is rather pointless. I can quite clearly see what is happening with your if statement and with your return. IMO comments should be used to explain the purpose of entire scripts/classes/functions and to explain any ambiguities or anything which isn't obvious from the code. Waste of time otherwise. Quote Link to comment Share on other sites More sharing options...
Guest Xanza Posted June 13, 2008 Share Posted June 13, 2008 Commenting, while doing any type of coding professionally is one of the greatest things you could ever do... Think about it, when you work for a small or even large cooperation many people work on any given piece of code to basically perfect it! And let's face it - no two coders think alike - so someone might do something totally un-necessary that you've never seen before in Code A, then use a practical way to implement it in Code B. Low if they don't comment, and maybe they are out of town or something you could end up re-writing already working code and cost time and money. Commenting is ESSENTIAL! Quote Link to comment Share on other sites More sharing options...
Darklink Posted June 13, 2008 Share Posted June 13, 2008 Personally i think your commenting is rather pointless. I can quite clearly see what is happening with your if statement and with your return. IMO comments should be used to explain the purpose of entire scripts/classes/functions and to explain any ambiguities or anything which isn't obvious from the code. Waste of time otherwise. Well thats nice for you. But remember, not everyone is as clever or have the patience to actually read the code and find out what it does themselves. If you see any decent script out there, it will be covered with comments like those. Scripts without, I find are very messy and have a very unfortunate programmer on it's head. Quote Link to comment Share on other sites More sharing options...
dsaba Posted June 17, 2008 Share Posted June 17, 2008 I would say a good rule of thumb is if the author can't figure out what a chunk of code does in about 20 secs, then you should comment it. The way OOP is taught and structured.. it takes care of most of the commenting in its structured obviousness, but most people find themselves commenting for structure on non-OOP code. At least I do... Quote Link to comment Share on other sites More sharing options...
Daniel0 Posted June 17, 2008 Share Posted June 17, 2008 Personally i think your commenting is rather pointless. I can quite clearly see what is happening with your if statement and with your return. IMO comments should be used to explain the purpose of entire scripts/classes/functions and to explain any ambiguities or anything which isn't obvious from the code. Waste of time otherwise. Well thats nice for you. But remember, not everyone is as clever or have the patience to actually read the code and find out what it does themselves. If you see any decent script out there, it will be covered with comments like those. Scripts without, I find are very messy and have a very unfortunate programmer on it's head. Seriously, try to read the code: if($show) { echo $string } (if show, echo string) How can any programmer not understand what that does? It's completely redundant. Quote Link to comment Share on other sites More sharing options...
GingerRobot Posted June 17, 2008 Share Posted June 17, 2008 I'd say the comment is more confusing than the code. "If show is enabled"? What does that mean? Quote Link to comment Share on other sites More sharing options...
redbullmarky Posted June 17, 2008 Share Posted June 17, 2008 ...But remember, not everyone is as clever or have the patience to actually read the code and find out what it does themselves. ... *cracks nuckles* Darklink - I sort of see where you're coming from, but those that haven't got the patience to read the code and understand it probably shouldn't be doing it in the first place. Remember - whilst PHP is easy in comparison to some other web languages, it's still a serious business and a 'profession'. I get tired of people that are trying to make money from this industry, ripping off clients by providing them with poor quality, bug-ridden junk, when they really don't understand things and haven't taken the time to, either. We see tonnes of "I'm doing a project for a client, and I got this code from somewhere but it doesn't work and I don't know why." and it really gets on my tits. If you don't know what you're doing and don't understand it FULLY, you shouldn't be doing it - ESPECIALLY for clients who are paying money, no matter how little. All it does is give those trying to make a living out of doing QUALITY work a bad name. A bad name for charging more than someone trying to make a quick buck and rip people off. A bad name as an industry. How ever you look at it - a bad name. If someone wants a web presence, then there are plenty of CMS's/Blogs, etc out there to build simple sites. If someone wants to get involved in coding and making money, then the same principles apply to PHP as they do with every other job - it's not some get rich quick scheme where you get everything without putting time and effort into it, expecting to make a living. Coding PHP can be fun as well, but it's not for the lazy who can't be arsed to put some effort in to learn their tools. In addition - if an uncommented script (aside from function/class names and the odd bit here and there) cannot be understood, then one of two things is wrong: a) the programmer does not know enough, and should keep on learning. b) the script is more than likely bad bad bad and not worth using anyway. *steps of soapbox* Quote Link to comment Share on other sites More sharing options...
Darklink Posted June 23, 2008 Share Posted June 23, 2008 Personally i think your commenting is rather pointless. I can quite clearly see what is happening with your if statement and with your return. IMO comments should be used to explain the purpose of entire scripts/classes/functions and to explain any ambiguities or anything which isn't obvious from the code. Waste of time otherwise. Well thats nice for you. But remember, not everyone is as clever or have the patience to actually read the code and find out what it does themselves. If you see any decent script out there, it will be covered with comments like those. Scripts without, I find are very messy and have a very unfortunate programmer on it's head. Seriously, try to read the code: if($show) { echo $string } (if show, echo string) How can any programmer not understand what that does? It's completely redundant. It's just an example. Of course there will be more to it. I don't comment every silly little line that. I thought that message would get across quite easily!!! Maybe I should make myself a little more clear in the future? Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.