5 ms·
The best argument I've seen here is that methods should be black boxes. Comments should reveal the input, output, and side effects of a method. There are two co
by nsmartt 13y ago
The best argument I've seen here is that methods should be black boxes. Comments should reveal the input, output, and side effects of a method. There are two compelling reasons for this:
- I can add to my own code, even if it's years old, without re-reading every line every of every method I need
- I can contribute to a code-base built by multiple people without reading every line they've written
- sounds 13y agoThat is a particularly useful approach in functional languages, where the function declaration itself is actually a fairly concrete guarantee of what the function will do. Shell scripts are almost the complete opposite end of the spectrum: Shell script functions are usually only created as a last resort. Global side effects (creating temporary files, changing global system state, global variables, etc.) are what shell scripts are all about. There are rare snippets of shell scripting that are different, using local variables and doing some sort of calculation, but that is the exception, not the rule. While ideally comments would be prolific, poetic, and perfect, some commenting is always better than none and most developers have bad habits of not commenting their code, so pushing them gently in the direction of more, not less, usually works.
- sillysaurus2 13y agoShell script functions are usually only created as a last resort. Hence why they'd prefer you write Python, not shell.
- sateesh 13y ago>> While ideally comments would be prolific ... I would rather put that the comments should be succinct rather being prolific. Better to put some explanation on tricky parts of the code as comments, and have method/function/class behavior as javadoc, pod, pydoc etc.
- sounds 13y agoYou could have just said: "comments should be succinct" :)
- nsmartt 13y agoAgreed. That's the purpose of the --help flag and equivalents.
- dmgd 13y agowhy would you need to re-read every line if you are looking at methods that have a single responsibility and that responsibility is clearly communicated through the name? (and parameter types/name, return types/names, in languages where some of those things are available)
- nsmartt 13y agoThe purpose may be communicated by the name, but the behavior can't (reasonably) be.