Look out for comments at the end of a block.

They may seem helpful, but they’re also a bad sign.

Sometimes when you see some complex code, the programmer will have comments at the end of a block to help identify which block is ending. This often happens when loops are nested several layers deep.

For example imagine an if statement inside a while statement inside another if statement inside three nested for loops. At the end of all this you find a half dozen end braces and you’re not sure which loop or condition is ending. Comments next the brace can seem like very helpful information at that point.

There are a couple problems with this. The first is that after a code refactoring in the code, the blocks may get rearranged. The comments can turn into lies. It’s pretty horrible to have comments that are no longer true.

The second issue is that code should never be so complicated that you need these kind of comments in the first place. Refactor the code, extract logic out. Keep doing this until the loops and blocks are obvious and easy to read. Simpler code is always easier to maintain, and you never get lost in the hell of multilayer blocks.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: