I totally agree with this. I like to put a bigger comment block at the top of my source files explaining the overall concepts and data structures used and then put few actual comments in the code. Instead I think about my variables and function names and make them talk for them-self. Commenting each and every element of your code will just make people (possibly yourself) curse at you when debugging your code and realizing that the comment was rendered obsolete 15 iterations prior and the code does something entirely different.
I've never seen a language's style guide recommend avoiding comments before
11–20 of 198 posts
Re: I've never seen a language's style guide recommend avoiding comments before
#12This submission needs to have a different title. It's not very clear whether the submitter is being genuinely surprised or sarcastic.
Re: I've never seen a language's style guide recommend avoiding comments before
#13This submission needs to have a different title. It's not very clear whether the submitter is being genuinely surprised or sarcastic.
I would say, never assume sarcasm is in play unless it's absolutely clear. So I think this title is fine.
If the OP meant to be sarcastic, that's just like me saying "yes" when I mean "no"---my mistake, not yours, and you can't be blamed for assuming I meant what I said.
Re: I've never seen a language's style guide recommend avoiding comments before
#14This is not convincing to me because the examples are trivial:
-- swap the elements of a pair
swap :: (a,b) -> (b,a) let b=a+1 -- add one to 'a'
Does it mean that every piece of code can be expressed as clearly as in a one-line comment in natural language? I don't think so.
Re: I've never seen a language's style guide recommend avoiding comments before
#15To rephrase - code makes comments understandable?
Re: I've never seen a language's style guide recommend avoiding comments before
#16Comment only magical code, but don't write magical code.
[deleted]
Re: I've never seen a language's style guide recommend avoiding comments before
#17Comments say what your code does, your code says how you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something shouldn't therefore change what it does. And this last part is specified in the comment.
Re: I've never seen a language's style guide recommend avoiding comments before
#18This is not convincing to me because the examples are trivial: -- swap the elements of a pair swap :: (a,b) -> (b,a) Yes this is redundant. let b=a+1 -- add one to 'a' Yes this is also redundant Does it mean that every piece of code can be expressed as clearly as in a one-line comment in natural language? I don't think so.
The argument is not to never use comments, but rather to avoid bad comments.
Re: I've never seen a language's style guide recommend avoiding comments before
#19Leo Brodie says in "Thinking Forth" in the style section: "The most-accurate, least-expensive documentation is self-documenting code". I am sure there are other prior examples.
Re: I've never seen a language's style guide recommend avoiding comments before
#20I'm a big believer in function level comments in code, in a sort of doxygen-ish style (I write mostly C).
It allows you to document the intended inputs and outputs of the function and state its purpose. This increases maintainability and reusability.
Functions themselves should be short and written as a sequence of logical steps.
I'm also a big fan of doing things right rather than just hacking until it works, which seems to put me in a minority.