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.This spawned from Check for proper inline comment formatting.
I disagree with this enforcement when inline comments are used to comment out code:
ERROR | Inline comments must start with a capital letter
Inline comments are often used to comment out code that one is working on, or to record a few lines of code that did not work or had problems or such. They may also be used to comment out code that is not complete, such as an optional else statement, or something that is still "todo". There are numerous other cases. In such cases, the capital letter rule is not applicable, the commented out code may use a keyword that is never capital.
Even the following triggers the above ERROR message.
// else {
// ..
// }Please relax this rule, it is clearly too strict and in my opinion unnecessary.
For what it's worth, I don't even think it is required when commenting out text remarks, but my issue report here concerns inline comments on code and code keywords, which I hope you can isolate if you still insist on keeping the capital rule for inline comments on actual text.
Comments
Comment #1
webel CreditAttribution: webel commentedIt's a matter of interpretation, but I am changing this from a "task" (it's also perhaps a feature request) to a bug. I feel strongly that developers should in this case not be told how to use inline comments so strictly.
Comment #2
webel CreditAttribution: webel commentedComment #3
webel CreditAttribution: webel commented@klausi again with sincere appreciation for your contributions. You wrote at Inline comments before code (as opposed to text) should not enforce: 'ERROR | No space before comment text; expected "//':
It's not a special case, it's one of the Java, C++, and PHP developers' worlds most common cases.
My idea is: get rid of the rule entirely (not just for code), or figure out how to not apply it to commented out code. The same goes also for Inline comments before code (as opposed to text) should not enforce: 'ERROR | No space before comment text; expected "//', but that is not as critical, because one can at least introduce the space and keep working with inline comments on code.
Enforcing a capital basically prevents the use of inline comments on code, which is IMHO ridiculous.
I have been working through a large perfectly well working and clear code set and it is taking days because of trivial rules like this that just plain annoy any experienced developer.
Coding standards are fine, but they shouldn't be an imposition that causes annoyance, time wasting, expense, or go against the grain of extremely common programming practice that is otherwise harmless. The practice of commenting out code with inline comments is harmless, useful, and very common practice, and this rule is reporting on it unnecessarily. Please, please get rid of it entirely if you can't figure out a way of only applying it to text not code.
Honestly, even for text, what does it really matter if it does not use a capital.
Comment #4
pfrenssenCommitting commented out code is very bad practice. And if you are breaking best practices anyway, why not simply surround the code with @codingStandardsIgnoreStart and @codingStandardsIgnoreEnd?
I strongly vote against including this in Coder because it will encourage bad practices.
Comment #5
klausiI agree, if you have commented out code that for whatever reason you don't want to remove then you can use the tags so that Coder ignores those lines.