That’s a really good argument for doing away with comments completely.
If you call your variable $squonk then to make it clear you need to comment what it is every single time it is referenced and not just in the header. Otherwise people may not know what it is as why should you need to read the comments in the header when you are reading the code. If they ca’t define meaningless variable names in comments then they would have to use meaningful variable names.
Anyway meaningless variable names should never get past code review.
It is annoyingly sensationalist, especially for a journal article, but it does raise some very valid points. A good proportion of comments are at best redundant.
…which are for human consumption. Whatever you’re using the docblocks for, eventually they are there to give developers help somehow.
Well I agree with the points made by TomB, although I feel it’s not that comments themselves are evil, but the developers who dont know how to write them properly. It’s the developers who need to improve, and to write more meaningful comments rather than repeat of their code. And of course, PHPDocumentor aint perfect and it creates some problems for developers.
With that being said, my primary issue with Symfony’s comments is that they are used as annotation, while PHP annotation is abomination. I know some people like this, but I for one firmly believe that comments should just be ‘comments’, not some form of black magic that alter the code’s behavior, an application that requires docblock comments to run properly is just plainly wrong.
The article title is too sensationalist Saying that comments are evil is far too extreme, however I agree that redundant comments are bad practice and descriptive function and variable names are better. However, there are cases where descriptions are necessary to make the code clear.
I fully agree with this reasoning, however I think for the time being this is the necessary consequence of PHP having its legacy and lack of features. phpDocumentor has been for a while and offered a way to annotate argument types but type hinting is still a new thing in PHP and still not complete so it’s not possible to infer every type from argument declarations. I think having some arguments annotated and some not is not consistent and would be worse for readability than just annotating all arguments and having type hints repeated. Repetition is never elegant but in this case it’s an acceptable compromise.
Since I started using phpDocumentor annotations I’ve found my code to be more readable. Most IDEs will auto-generate them instantly so the effort is almost none. If I don’t feel I need any descriptions I just generate annotations with argument types and leave them like this. This has the advantage of coming back to the code later on and being able to add any description easily because I already have the place to add it. For me the benefits in this type of consistency outweigh the ugliness of repetition and redundancy - which is not really ugliness since I always set my IDE to display comments in bright magenta so they nicely stand out from the code and in the worst case (when they don’t describe anything that’s not in the code) act like visible delimiters between method declarations.
BTW, Tony, when reading the code of your DICE a while ago I wished every method with all its in and out arguments had been annotated as I found it hard to understand quickly what each method specifically does - and I really wouldn’t mind if some of the annotations were redundant
I am aware most people keep comments in pale font. I have tried both ways and after a while I’ve always come back to bright colours. Comments may seem to be less important because they are not executed but I am of the opinion that comments are important to the programmer so keeping them visible makes sense. Maybe this even keeps me from writing redundant comments because there would be too much magenta on the screen . Here it is:
Of course this is purely subjective, just a personal preference. A few months ago I took to writing a mobile app in Android Studio - a different IDE and I kept the default grey comments just to see if maybe they would make more sense to me. After a month I changed them to magenta and immediately felt improvement in code readability
Oh, indeed! I know he is Tom, I just made a typo, I don’t know why… Unfortunately, I can’t edit my post, so Tom please accept my apologies
Actually, the contrast to white with magenta seems to make the comments meld a bit into the background or rather the code still stands out well. So, yeah. It could work for me too, if I used a white background, which I don’t. It is scientifically proven that working with a white background is harder on the eyes and I also notice it too, working on other text content, like in Word or Markdown editor, the white background makes my eyes tired faster.
Ok. Back on topic. Comments are like guns. They are only bad, when misused or used improperly. The better question is, what is a proper comment? I looked up comments in PHP the right way and the only mention is documenting code according to the informal PHPDoc standard.
You are right - the comments meld into the background but are still quite visible, more than grey, which means the sweet spot for me.
Yeah, I’ll have to try it. The problem for me is that while I could make my IDE dark it’s difficult to make other programs dark and I don’t like the high contrast of having one application dark and another light, so I prefer to keep everything light and simply turn down monitor brightness. And I think the tiredness has a lot to do with display quality - after all there is no problem reading white books in natural light. Harsh and unnatural light coming from the monitor certainly is not healthy and then dark backgrounds help because we reduce the overall amount of artificial light coming from it.
To me this is simple: first, make the code self-explanatory by using proper names, logical division into methods, etc. When something is not fully clear from the code alone - add a comment. I just imagine if the code would be clear for an outside programmer - if not, then it’s a good place to add a comment. Very often the outside programmer is me after a few months or years and then I’m grateful to myself for commenting
Ideally the code itself should be clear enough to understand what it does.
It should also be unnecessary most of the time to explain how it does what it does.
What always needs commenting is why a piece of code uses a less obvious approach than might normally be expected - such as when a small piece of code needs to process a huge number of transactions where making the code clear and easy to read also makes it very slow and inefficient and so the code has been rewritten in a less obvious way in order to save hours of processing time.
What I find often missing with documentation, and this is a bit off-topic from code commenting, is not how the code specifically works, but the overarching concepts the design decisions are trying to cover. Tom’s Dice project is a great example of what I mean and how to do it correctly. With Dice he has a 100 line class for dependency injection, but has written practically half a book about what it is all about and how it is useful. To me, this is what marketing is actually all about. So, I’d say, proper marketing of a work of code, in the sense of telling its greater story, is incredibly important, in addition to decent code comments.
That’s documentation rather than comments. All projects should have several different documents associated with them aimed at the different groups involved - technical specifications, user documents etc. Proper documentation can easily run to somewhere between 10 & 100 times the number of lines of code.
Let’s imagine all arguments are given proper descriptions in this phpDocumentor style. Aguments $questions and $answerSets are the same in two methods and one method simply passes them over to the other. What do you think would be the best way to handle this - repeat the same descriptions in two places or just have them in one? The passing of arguments could occur in more places so potentially the same description would need to be repeated more than two times. I’m still undecided on the best approach, what’s your opinion? Possibly, a good IDE could handle such cases automatically but I don’t think Netbeans (which I use) has such a feature.
Yes, if it is a lone programmer on his own site or application, documentation (or marketing of the code) isn’t necessary. If it is anyone selling or giving away the code for further use or extension, then it is undeniably important.
It’s not even that. You’re in a completely seperate field at that point.
If we’ve gotten to the point of looking at code comments, your marketing has already done it’s job - you’ve convinced the person/company/whatever (it does NOT have to be a ‘lone programmer’) to use your code. If they’re looking through the comments/documentation of your product, you’re trying to convince them not to give up on your code - so going into flowery overarching statements is counterproductive.
Provide a sales brochure to the guy doing the purchasing. Provide a reference manual to anyone actually using the thing.
If it is an end product with a user base, then we are talking about a different kind of target for the marketing. It would be actual end users and not programmers, so the story being told needs to be different for sure. I am thinking more along the lines of devs being the client developers of the code. You still need to market it to them too and I am not sure a reference manual is going to be totally compelling.
I agree with you, with a caveat: Describing a method in a class often doesn’t give you a firm definition of how it’s used or what the class actually does. It’s like asking the question “What does a piston do?” while trying to explain the function of an engine and while useful on its own, it doesn’t give you enough of the bigger picture to put it all together. In functional programming the function is self contained but in OOP it’s the class that does something and the methods rely (and can act differently) depending on the state of the object. This is difficult to convey by providing @param annotations and a short description. Understanding what a cell does won’t help you understand how a kidney works, for example.
That said, yes descriptions probably would help people who were looking at the code, rather than just wanting to use the library.
I completely agree with this. Look at the PHP manual, now imagine it was just a reference manual that contained the kinds of things you see in docblocks: a 1 line description, @returns, @param etc. Will this be useful? For some functions, yes, for others… not really. When I look something up on the manual the first thing I look at this the example code as it far more quickly conveys what it does than a short description.
Saying that comments are evil is far too extreme, however I agree that redundant comments are bad practice and descriptive function and variable names are better. However, there are cases where descriptions are necessary to make the code clear.
