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".