in reply to The sourcecode *is* the documentation, isn't it?

Here is a piece of advice I find has merit:

Let the source code say what you are doing, add comments to say why you are doing it

cheers

tachyon

  • Comment on Re: The sourcecode *is* the documentation, isn't it?

Replies are listed 'Best First'.
Re^2: The sourcecode *is* the documentation, isn't it?
by dfaure (Chaplain) on Jun 15, 2004 at 08:45 UTC
    Let the source code say what you are doing, add comments to say why you are doing it

    I totally, completly agree with you. There's no worst comments than those duplicating informations given by the code since usual coding practices tend to make forget having them synched.

    Until you're not a Befunge of APL developer, the language you code with has usually enough semantic elements helping you to understand what is meant in there.

    Nota: English is not my mother longue but I can manage to understand approximatively what is meant here without any comments available :-)

    HTH, Dominique
[reply]
Re^2: The sourcecode *is* the documentation, isn't it?
by adrianh (Chancellor) on Jun 15, 2004 at 09:56 UTC
    Let the source code say what you are doing, add comments to say why you are doing it

    I'd go a bit further and say that if you have to add comments to explain why you're doing it you should reconsider and see if there way you can rewrite your code to express your intentions more obviously.

    Comments are a good thing if they make non-obvious code easier to understand. Even better is to make the non-obvious code more obvious.

[reply]

In Section Meditations