Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

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

by tachyon (Chancellor)
on Jun 15, 2004 at 01:25 UTC ( [id://366739]=note: print w/replies, xml ) Need Help??


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

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
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.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://366739]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others surveying the Monastery: (7)
As of 2024-03-28 19:04 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found