Best way to comment on if/else statement with PHP PSR-2

Question

In my opinion, sample #2 seems to be the more readable way of commenting.

But if I apply PSR-2 to both samples, sample #1 won't change but the result of sample #2 changes as below and it's not a proper comment.

What is the best way to comment in these case?

sample #1

/* Read cached data */
if ($useCache == true){
    // do something
/* Download and cache data */
} else {
    // do something
}

sample #2

/* Read cached data */
if ($useCache == true){
    // do something
}
/* Download and cache data */
else {
    // do something
}

PSR-2 result of sample #2

/* Read cached data */
if ($useCache == true){
    // do something
} /* Download and cache data */
else {
    // do something
}

Conclusion 2017/12/13

So far the best way seems to be as below: Marking them inside the brackets

if ($useCache == true){
    /* Read cached data */
    // do something
}
else {
    /* Download and cache data */
    // do something
}

I would think the comment would be inside the else brackets. — Ibu, Oct 15 '17 at 06:53
In my opinion you should try to name variables and functions good enough to not have to use comments. Often when the code is updated the comments will not be updated. For instance would you remember to update the comments when you fix the spelling error and change the code from `$useCash` to `$useCache`? — rypskar, Oct 15 '17 at 10:33
>`For instance would you remember to update the comments when you fix the spelling error and change the code from "$useCash" to "$useCache"?` @rypskar Gee... thanks for pointing that out! I've fixed it. As you mentioned, it's true that having variables and functions named good enough so not to use comments, but I had to de-spaghetti the codes, which the former people left, before refactoring and else and learn the right way. — KEINOS, Dec 13 '17 at 09:25

Calimero · Accepted Answer · 2017-10-15T07:07:46.440

PSR-2 doesn't address how to make comments or block comments on purpose, so you can do as you please.

There are many elements of style and practice intentionally omitted by this guide. These include but are not limited to:

Declaration of global variables and global constants

Declaration of functions Operators and assignment

Inter-line alignment

Comments and documentation blocks

Class name prefixes and suffixes

Ref : http://www.php-fig.org/psr/psr-2/#conclusion

However, acording to PSR-2, the opening brace should be separated from the if() condition by a space character, and the else should be on the same line and next to the preceding closing brace, like so :

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

Ref: http://www.php-fig.org/psr/psr-2/#51-if-elseif-else

Imho, your comment being relative to what is done inside the else block is a pretty good reason why it should be placed inside that block (only functions, classes and top-level constructs have the privilege to have a docblock extracted above them), so I tend to agree with Ibu's comment in that respect (If you were to edit or delete the else block at some point, the block comment should be updated as well).

KEINOS · Answer 2 · 2017-10-16T23:02:45.603

1

@Ibu Indeed. As of @Calimero said, it might be like this?

if ($useCache == true){
    /* Read cached data */
    // do something
} else {
    /* Download and cache data */
    // do something
}

edited Oct 16 '17 at 23:02

answered Oct 15 '17 at 10:02

KEINOS

1,050
2
13
32

Best way to comment on if/else statement with PHP PSR-2

Conclusion 2017/12/13

2 Answers2