Code Comments Practices

Discussions debate the purpose and best practices for code comments, emphasizing that they should explain 'why' the code behaves a certain way rather than 'what' it does, versus self-documenting code.

📉 Falling 0.4x Programming Languages
5,299
Comments
20
Years Active
5
Top Authors
#9054
Topic ID

Activity Over Time

2007
3
2008
70
2009
83
2010
91
2011
150
2012
330
2013
344
2014
371
2015
138
2016
279
2017
269
2018
329
2019
393
2020
312
2021
449
2022
415
2023
499
2024
378
2025
340
2026
56

Keywords

LLM DedupeStrings strings.Sort ID i.e ADHD ADD code comments explain commenting code does comment code don documenting write code written

Sample Comments

Thorrez Jul 13, 2019 View on HN

Can't you just add comments to the actual code saying those things? I've seen code comments saying those exact things.

marginalia_nu Nov 17, 2022 View on HN

In general, I feel comments should explain why the code is the way it is, not what it does.

ska Apr 5, 2018 View on HN

commenting is not a good replacement for cleaner code, because they can drift and lie.

dkuntz2 Aug 12, 2013 View on HN

You must be doing comments wrong. If they explain the why, they should still be relevant. Or people should rewrite them when they adjust the code...

Never. Comments should clarify what code does or why it does what it does. Nothing else.

disputin Jul 23, 2014 View on HN

I think the saying is that comments explain why the code does something.

sanderjd Jul 23, 2023 View on HN

Comments aren't for "what does this code do?", they are for "why does this code do this?".

baggachipz Oct 21, 2011 View on HN

Don't like my comments in my code? Don't read 'em. They're useful to some people.

wtetzner Aug 21, 2012 View on HN

You seem to be missing the point of comments. Comments are not meant to explain what your code does. They are for explaining why.

codegeek Oct 13, 2021 View on HN

Good code should have some comments. Not for the "what" but for the "why".