I prefer either:

if ($magic == big) { bigMagic(); } else { smallMagic(); } 

or:

if ($magic == big) { // big magic requires a big surprise, so I'm telling you about it here surprisingThing(); } else { // give a magical feeling even if $magic is noMagicAtAll smallMagic(); } 

It seems a little silly to write a comment explaining what your condition checks unless the code doesn't clearly state it. Even then, better to rewrite the code to make it as clear as possible. The same goes for the bodies of the conditional blocks -- if you can make the reason for doing something obvious, do that instead of commenting.

I don't subscribe to the "never write comments" philosophy, but I do believe in avoiding comments that say what the code should be saying. If you write a comment like "check what kind of magic should happen" when the code could say if ($magic == big) {..., readers will stop reading your comments very quickly. Using fewer, more meaningful comments gives each of your comments more value, and readers are much more likely to pay attention to those that you do write.

Choosing meaningful names for your variables and functions is important. A well-chosen name can eliminate the need for explanatory comments throughout your code. In your example, $magic or maybe $kindOfMagic seems like a better name than $big since according to your example, it's the "kind of magic" that's being tested, not the "bigness" of something.

I prefer either:

if ($magic == big) { bigMagic(); } else { smallMagic(); } 

or:

if ($magic == big) { // big magic requires a big surprise, so I'm telling you about it here surprisingThing(); } else { // give a magical feeling even if $magic is noMagicAtAll smallMagic(); } 

It seems a little silly to write a comment explaining what your condition checks unless the code doesn't clearly state it. Even then, better to rewrite the code to make it as clear as possible. The same goes for the bodies of the conditional blocks -- if you can make the reason for doing something obvious, do that instead of commenting.

I don't subscribe to the "never write comments" philosophy, but I do believe in avoiding comments that say what the code should be saying. If you write a comment like "check what kind of magic should happen" when the code could say if ($magic == big) {..., readers will stop reading your comments very quickly. Using fewer, more meaningful comments gives each of your comments more value, and readers are much more likely to pay attention to those that you do write.

Choosing meaningful names for your variables and functions is important. A well-chosen name can eliminate the need for explanatory comments throughout your code. In your example, $magic or maybe $kindOfMagic seems like a better name than $big since according to your example, it's the "kind of magic" that's being tested, not the "bigness" of something.

Say as much as you can in code. Save prose for the cases that demand more explanation than you can reasonably write in code.

I prefer either:

if ($magic == big) { bigMagic(); } else { smallMagic(); } 

or:

if ($magic == big) { // big magic requires a big surprise, so I'm telling you about it here surprisingThing(); } else { // give a magical feeling even if $magic is noMagicAtAll smallMagic(); } 

It seems a little silly to write a comment explaining what your condition checks unless the code doesn't clearly state it. Even then, better to rewrite the code to make it as clear as possible. The same goes for the bodies of the conditional blocks -- if you can make the reason for doing something obvious, do that instead of commenting.

I don't subscribe to the "never write comments" philosophy, but I do believe in avoiding comments that say what the code should be saying. If you write a comment like "check what kind of magic should happen" when the code could say if ($magic == big) {..., readers will stop reading your comments very quickly. Using fewer, more meaningful comments gives each of your comments more value, and readers are much more likely to pay attention to those that you do write.

I prefer either:

if ($magic == big) { bigMagic(); } else { smallMagic(); } 

or:

if ($magic == big) { // big magic requires a big surprise, so I'm telling you about it here surprisingThing(); } else { // give a magical feeling even if $magic is noMagicAtAll smallMagic(); } 

It seems a little silly to write a comment explaining what your condition checks unless the code doesn't clearly state it. Even then, better to rewrite the code to make it as clear as possible. The same goes for the bodies of the conditional blocks -- if you can make the reason for doing something obvious, do that instead of commenting.

I don't subscribe to the "never write comments" philosophy, but I do believe in avoiding comments that say what the code should be saying. If you write a comment like "check what kind of magic should happen" when the code could say if ($magic == big) {..., readers will stop reading your comments very quickly. Using fewer, more meaningful comments gives each of your comments more value, and readers are much more likely to pay attention to those that you do write.

Choosing meaningful names for your variables and functions is important. A well-chosen name can eliminate the need for explanatory comments throughout your code. In your example, $magic or maybe $kindOfMagic seems like a better name than $big since according to your example, it's the "kind of magic" that's being tested, not the "bigness" of something.