Writing Comments Is Lazy Coding
Writing Comments Is Lazy Coding
Andrez Sainz de Aja writes that comments are a code smell: they make us lazy. Instead of using comments to convey intent, the coding should. But that is hard, so it is easier to write dumb coding and just put the intent into comments.
Comment your public methods >:c
Literally working on a legacy project atm, opened up one file that was over 14k lines long amd had several hundred methods shoved into it, not a single comment to be found.
Not auto-generated, just lazy coders over 10+ years that kept shocking shit into this class willy-nilly with no regard.
There's largely 2 places for comments:
-
Public methods should always get documented
-
Anytime you have to explain why. You don't typically meed to comment the "what does this do" part unless you've written something very difficult to read for optimization reasons. But anytime you would have to explain "why did you do that", you absolutely comment that.
Basically if someone else reads the code and you have a section that would make them go "wtf, why did they do it that way", and you'd respond with "ah yeah so it's because if you don't do it that way this other thing happens"... then you absolutely must put a comment in.
-
Comment anything in your code up to an ungodly amount! Code is for humans to read. The computer does not care about the comments.
From the perspective of maintenance and technical debt: yes, you do want your code to be as clear as possible. But some languages, like assembler and mindfuck, simply weren't designed to be semantically expressive. Assembler clearly states what is happening but not why. And mindfuck is created to be as hard to parse by humans as possible. Without a description of why things exist or what they should be doing, you're going to have a bad time.