Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple APILearn More
iamai25181yWhen you are in-the-zone coding you kind of forget to comment. But there should be a time to review the code when you can do some clean-up and put the comments. Human memory needs a lot of reminding and the comments really do speed up the recollection process.
Comment what needs to be commented, document what needs to be documented and the most important: Keep it uptodate.
No comments means - as a matter of fact - that at least every individuum who reads the code is left to his own interpretation...
And I think it's obvious how bad that can end... *cough* standards *cough*
Marl3x28041yI just can't imagine someone sitting in front of some piece of code and being like: "WTF, why are there comments?!"
How elitist do you have to be?
> And I think that's ridiculous.
and its far more important to document the 'why?' way more than the 'what?'
I've had my share of arguments with 'senior' devs who like to beat up junior devs in code review for not having the XML comment headers. I say, who cares? Unless the header contains 'why' the method/class/whatever is necessary, I don't care. I can read the code and figure out the 'what'.
A LOT of my comments say things like "Had to hard-code 999 for the quantity check because VP-Bill said if I didn't, I wouldn't have a job. The actual users of this application will eventually want this changed."
I still get emails from devs saying "Ha ha...read your comment from a month ago when I was told to remove the 999 quantity check because it was stupid."
witchDev6231yI am all for minimum comment on the less obvious stuff but I started working with a supposed senior DEV recently who thinks it's just bad practice to write ANY comments and I can't agree with that. Some things are obvious and naming convention covers it but somethings are really not so why waste some why waste someone else's time.
No matter how Tony Stark you are some things cannot be written keeping the readability in perspective. I am sick of these self-proclaimed programming Gods. They think their functions and variable names can be so on point that they do not need to comment the code. They still wanna use nano or vim for web development even.
Calm the fuck down. Writing good code should be an art and a beautiful and thoughtful experience not a self torture session. How can I forget about those who still wanna use Linux without a desktop environment because they are motherfuckin hacker wannabe.
I have put comments in my code that say, "Not sure why this is working." I came back a few days later and saw the comment. Then I took a quick look at the code. I was able to discern why it was working. So I removed the comment. So even in short term comments can be useful to the dev that wrote the comment. There are other areas where there was some tricky code that I commented why it was there. Some things look out of place and might get removed if the reason is not apparent. So I can see comments preventing bugs by devs later on.
That's exactly what code should document itself is about.
There are techniques to make code document itself, e.g.: Keep functions short and use abstraction layers.
If you then have to drop a comment because you couldn't figure out how to make this code self-explanatory, then this is the only fucking comment and I will actually read it.
But people who demand comments everywhere are like hey:
- "You know this two line function called readLineFromStandardInput has no comment."
- "It is self-explanatory"
- "Our coding standard demands to comment every function"
- "alright... // read a line from standard input"
Self-documenting code ensures that people will actually read your bloody comment whenever self-documentation failed. Most comments are just clutter.
I get what you are saying, but not all code documents the why (only the how):
This is from a much larger codebase. Obviously this example is cherry picked. But even reading the docs may not describe why this cachebuffer is set. Or set to a large number.
So why is this set? The comment preceding explains:
// this is needed to keep listview from stuttering
The rest of that block is uncommented as the rest is straightforward standard use of properties and functions. So yeah, there needs to be a balance.
I wholeheartedly agree. COMMENTS EXIST FOR A REASON. To explain weird behaviour. People who say comments==bad code are morons who just overheared a "using comments all over the place with irrelevant contents and/or explaining every single thing you do in them means you have wrote code that is not self explanatory" and are trying to play smart by BANNING EVERY SINGLE COMMENT.
@Marl3x You obviously don't work with people who put in comments just to look like they are doing something productive..
For example comments for docs.. Method had one extra param added, person just copy pasted above comment for a different parameter, left in the wrong type, name and the description..
So yeah, fuck comments that are useless (even dangerous) because they're plain wrong!! No need to be elitist to hate this shit..
Marl3x28041y@sladuled I know what you mean.
I saw comments like: "We need this because blabla...", or like you said simply some copy pasted generated one.
But still, I've never thought: "Why is there a comment?", I was rather like: "Who the fuck wrote this shit?". It would have still been helpful if the person writing it gave a shit.
And I was talking about comments that don't necessarily help you, but are just there. I would still rather have something that explains the code a little bit that just have a 100 line method with 20 if statements, that's just there.