Hacker News new | past | comments | ask | show | jobs | submit login

I guess I have been lucky but I don't really get this. You read comments along with the actual code right? They complement one another. An out of date comment should not ipso facto render code indecipherable and if it does that speaks to a bigger problem with the code itself.

I find it strange that people want to throw the baby out with the bathwater when it comes to commenting code just cause they've been bit before.




You don’t see how you could end up wasting time when a comment led to you making an incorrect assumption? If they don’t affect how you read the code would mean they’re useless.


I can see how it could, in theory, if the code is extremely complicated and then the comments are lying to you on top. Again I have never experienced this or anything even close to it in 1.5 decades of coding on teams. Unless every comment is wrong then some of them are useful to someone.

On the other hand, I have been bit plenty of times by incorrect documentation outside of code about libraries and APIs.


Well, consider that such documentation is often generated from comments.


Fair enough. I will say my recommendation is for writing useful inline comments ("the why" comments and more rarely "the what").

File-level and function-header type comments that tend to generate docs (eg. Doxygen) are certainly more likely to fall out of date (easy to miss in a PR diff etc) and I don't really support using them anyway.




Join us for AI Startup School this June 16-17 in San Francisco!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: