Therefore when we jumped both feet into Clojure we unconsciously brought with us the belief that comments just weren’t needed
I used to be in the "code tells a story, no comments needed" camp. In large part because two of my three university courses had automatic marking system which detracted points if comments exceeded a certain percentage of text mass. Habits!
Gradually I've been finding myself commenting more and more in my code. In FP (mostly F#) code I almost always end up with some incredibly information dense set of lines that needs at least some defense of its existence.
Having spent some recent weekends reading the sources of id-software games[1] I've started to really think about the approach to comments in imperative code too. I've started commenting lots and then cutting it down later. If anything, it helps me reason about my code better.
On a totally separate tangent, I feel like the kernel of most of my FP code for data processing is essentially array programming like APL / J, just way way way more verbose.
I don't trust myself to know - while I'm writing code - how well I or anyone else will understand it cold. So if I'm in any doubt at all I leave a comment. Sometimes I do go back and remove them - refactoring has to include comments.
Whenever we discuss this topic there are usually some defensive sounding remarks about the fact that inaccurate comments are much worse than no comment. This is certainly true but I don't share the conclusion that the only reasonable answer is to never leave a comment. I guess if that is already what you do, then its probably easier to conclude it is correct.
> In large part because two of my three university courses had automatic marking system which detracted points if comments exceeded a certain percentage of text mass
That sounds like a horrible system. Why'd they ever do that? The grading systems I have seen do the inverse, requiring certain amount of comments. That of course leads students writing gibberish just to fulfill the comment quota, but even that is better than penalizing for commenting.
There speaks somebody who has never spent their evenings wading through terribly project submissions with > 70% comments.
The 'why' would be that there's an entire class of newbie developer who write opaque code, and use the comments as an excuse not to write code clearly.
I see too many developer with the general attitude 'This code is opaque - it needs a comment', where I vastly prefer 'This code needs a comment, how can I make it less opaque.'.
I used to be in the "code tells a story, no comments needed" camp. In large part because two of my three university courses had automatic marking system which detracted points if comments exceeded a certain percentage of text mass. Habits!
Gradually I've been finding myself commenting more and more in my code. In FP (mostly F#) code I almost always end up with some incredibly information dense set of lines that needs at least some defense of its existence.
Having spent some recent weekends reading the sources of id-software games[1] I've started to really think about the approach to comments in imperative code too. I've started commenting lots and then cutting it down later. If anything, it helps me reason about my code better.
On a totally separate tangent, I feel like the kernel of most of my FP code for data processing is essentially array programming like APL / J, just way way way more verbose.
[1] https://github.com/id-Software