Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Calling it a bug's a bit harsh, but this really only applies if one is commenting out sentences:
ERROR: Inline comments must end in full-stops, exclamation marks, or question marks.
It could at least be relaxed from ERROR to a WARNING, calling the following errors is just plain silly.
Why is this an ERROR ?
dpm($var);
// DEBUG
Or this:
// TODO
Or this:
// CHECK
Why should I have to spend my time editing the above so that it reads like this ?
// TODO.
What is the compelling "value add" there ? I can't see one. I find it just plain annoying.
The rule should only apply to full text sentences, if at all.
Comments
Comment #1
YesCT CreditAttribution: YesCT commentedThose look like temporary comments used while developing. And should not remain when code is final. So errorring on them seems appropriate.
You would want to spend your time changing
// TODO
to
// @todo Update this to use the new cachable strategy once http://drupal.org/node/123456789 is in.
or
// @todo Convert this to use field definitions in http://drupal.org/node/123456789.
Note though the example in https://www.drupal.org/node/1354#todo
is like:
// @todo Remove this in D8. http://www.drupal.org/node/1234567
So maybe the rule could be updated with a pattern to allow sentence followed by url?
Comment #2
webel CreditAttribution: webel commentedNo, I want them in there, it's a tutorial module, and I want to be able to use inline comments for educational purposes:
I want to be able to say for example that something needs to be refactored, and I want to be able to easily search for it in NetBeans IDE, which means also sometimes indeed after a statement, like this
As long as it's not over 80 lines that should be fine.
For what it's worth, I don't think code is ever "final". I like sometimes to leave remarks and records of what I have done (including what did not work, such as code) for the world to see. If I use say inline comments on code, Coder complains about rules that are intended for text, not for code, or for code-like tag words like // DEBUG, which belong on the same statement line.
An exclamation mark on say //DEBUG! (oops, habit, am meant to write // DEBUG! with a space of course):
I can then search on that easily in NetBeans and the search results show the code that I marked.
Comment #3
webel CreditAttribution: webel commentedI can do this easily, and turns out NetBeans already supports '@todo'.
For NetBeans Users
For whatever reason, the capital TODO has been the convention in NetBeans IDE. See for example (note article title has 'TODO' upper case) Show TODO comments in the Task List window of NetBeans.
The article is followed by a table figure that shows both @todo and TODO and others already there (that is from 2008, so older Netbeans). In NetBeans8.0 I found it instead under:
See also NetBeans8.0 help, just search for todo. My fresh NetBeans8.0 install already had: @todo, TODO, FIXME, XXX, PENDING …
Comment #4
webel CreditAttribution: webel commentedAt least. One currently also can't use inline comments to comment out code, or code-like words (other than @todo).
Does commented out code have to have a 'full stop, exclamation mark or question' at the end of it ?
I simply don't accept that Coder should flag on all commented out code, unless you introduce a STRICT mode and support other compliance levels corresponding to rule switch sets, in a Coder config file. Modules like mine, with other needs (educational, tutorial, UML friendly) can then choose to not use STRICT mode yet still benefit from Coder.
Otherwise it just pollutes the output from Coder, and makes it hard to catch other errors that matter more (than harmless commented out code).
Comment #5
klausiIf you have commented out code that you want to keep you should use
Otherwise I think the check for comments ending in full stops is fine; you should really explain your @todos in a sentence and end it properly.
Comment #6
webel CreditAttribution: webel commentedComment #7
webel CreditAttribution: webel commentedRelated: #2463409: Request shortcuts for @codingStandardsIgnoreStart/@codingStandardsIgnoreEnd.
@YesCT wrote:
And exactly when, may I ask, is code ever 'final' ?
Besides, I have compelling educational reasons to leave certain marker comments in the code, and I simply do not agree that all inline comments require punctuation at the end, or that very brief inline comments should not follow code on the same line (noting that I am nevertheless doing my best to adhere to these rules, assisted by TIP: PHPCSMD: a plugin for PHP Code Sniffer compatible with NetBeans8 and the Drupal Coding Standards from Coder).
Comment #8
kentr CreditAttribution: kentr as a volunteer commented@webel:
For what it's worth,
// @todo
(without anything after it) doesn't throw an error for me.Besides conforming to Drupal coding standards, another advantage of using
@todo
is that Doxygen claims to automatically create todo lists from them. Though, that probably only works within Doxygen-style comments, which may violate the Drupal coding standards regarding inline comments.