What is a good way to comment if-else-clauses?

Posted by acme on Programmers See other posts from Programmers or by acme
Published on 2012-04-04T10:25:42Z Indexed on 2012/04/04 11:40 UTC
Read the original article Hit count: 186

Filed under:

Whenever I'm writing a typical if-else-construct in any language I wonder what would be the best way (in terms of readability and overview) to add comments to it. Especially when commenting the else clause the comments always feel out-of-place for me. Say we have a construct like this (examples are written down in PHP):

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

I could comment it like this:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

or

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

or

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

What are your best-practice examples for commenting this?

© Programmers or respective owner

Related posts about comments