Hi,
so i guess its a bit unfair to complain as a lot of people have spent a lot of time providing scripts on various websites but i find that a fair amount of people use
/* this is a comment */
rather than
// this is a comment
Why do you care either way? i hear you ask… Well if i am chopping a piece of code around to fit or testing bits of code whilst i am debugging something i often want to quickly comment a block out. If the script has been commented throughout with the first style then i can’t comment out a block as my new comment stops at the first instance of */ so i now have to go through and change the comments all to // or remove the code and keep it safe whilst i am testing stuff.
Am i missing a trick somewhere or do other people find this as well?
/**
* A multiline Comment/DocBlock (notice the two astericks at the start)
* @returns $something (this will be parsed by e.g. phpDocs)
*/
/* Multiline comment,
eveything gets
commented out
*/
// A single line Comment
// Needs '//' at the start of every line
Your running into the same problems we all run into at some point . It’s actually bad practice to litter your Code with comments.
Your methods should be small enough to understand without them. Once you get into the routine of generating ApiDocumentation (http://www.phpdoc.org/), using VCS (git) and Unit Testing (https://phpunit.de/) you will find that your rarely need to add anything outside of a proper commit message. Why resuse the same file, commenting out sections of code when you can just as easily fork/branch the project and clone it to your IDE.
I just wanted to add something here: There’s nothing worse than autogenerated phpdocs that offer no information that isn’t already available in the method header. It’s utterly meaningless without proper explanations of the arguments/method. With PHP7, @returns will even be redundant in a lot of cases
PHP supports all three styles of comments. Of course as pointed out above you should seldom need comments if you write your code in a way that makes it self documenting.
The main reason I can think of for using a comment would be where you have used a not so obvious way of doing something for efficiency reasons and add a comment to remind those updating the code later of what the code does and more importantly that changing it to a more readable version will make the code so slow as to be unusable and so to leave it alone.
Would I be correct in saying, when code represents the API, that part of it should be documented well, so the client dev has a better understanding of how to apply it?
Hmm… yes. I am also coming from a perspective, where the underlying API code isn’t directly viewable too. But yeah, I understand if the code is reviewable and readable, a lot of documentation shouldn’t be necessary.
I can’t help but wonder why you’d using automatically generated docblocks to generate automated docs… skip the middle man and generate the site from the code.
You guys all seem to have this bias on commenting rooted in the fact that you believe your code is “easy” understand. I can without a doubt say that it isn’t – it never is – you or any other programmer. Engineers whom don’t at least some level commenting are lazy and inconsiderate.
What I am saying is that if it isn’t then it should be rewritten to make it easier to understand rather than adding comments which will soon be out of date. Only where there is a reason for using code that is not easy to understand should you comment the reason why it does what it does that way rather than using easy to understand code.
There has always been a tendency to not update comments when code is changed. I have come across lots of comments that tell you what the code used to do and which are therefore worse than no comment at all as the code no longer does what the comment says.
. It’s actually bad practice to litter your Code with comments.