in reply to A Question of style.

Code Complete has (as usual) a lot of good things to say about indentation style. The best IMO is that programming expertise is fragile. Changing any of many apparently insignificant details can ruin an expert programmer's efficiency. It is possible to learn not to be so hampered by details, but they matter.

If you ever have to use another form of indentation for long enough to become used to it, I predict that you'll discover that your present preference is entirely due to this fragility. You mentally block code based on the indentation style, and facing an unfamiliar indentation style you need to start thinking about that, which gets in the way of everything else that you do.

However there are other people who would have exactly the same issue with how you indent code.

BTW about commenting, if you really put comments on every block, you're probably overdoing it. Remember, comments start with as many bugs as code does, but bugs in code get fixed. And code tends to be better maintained than comments. Therefore if your comments reiterate what your code does, then experienced programmers are likely to ignore the comments.

The mantra is to make the code, as much as possible, its own comment. You do this with well-chosen variable names, function names, and so on.

Does that mean that you can remove comments? Of course not. But in the long run I've found, as I0 put it once, I find the most useful comments state what remains invariant, while the code states what gets transformed. In that way comments document what you need to know when editing the code, but changes to the logic are less likely to require re-writing comments.

A relevant thread is Re (tilly) 2 (disagree): Another commenting question,. As I always point out when I bring up this thread, the thread was accompanied by a private chat between me and DeusVult. The tone of the thread was far more confrontational than the chat, so this thread doesn't really capture the actual tone of the full conversation. But still it is worthwhile reading.

Replies are listed 'Best First'.
Re^2: A Question of style.
by GrandFather (Saint) on Jun 08, 2005 at 02:28 UTC

    Excellent reply. Thank you for the links. I guess you recommend Code Complete? :-)

    I agree fully with your comments about comments and names, and indentation actually too. Our experience is indeed that programming expertise is fragile (legacy K&R formated code in our software really slows us down).

    No, I don't comment each block as illustrated. On reflection that was a rather illustration. Hey-ho.


    Food for thought, not fuel for flames.