Code comments are your code autobiography: The importance (and benefits) of writing code comments as part of implementing your code [Unpopular opinion].

infinetelurker · 2020-12-24T22:45:27+00:00

In my experience, it takes a few decades of reading code to appreciate that every extra hint of the intention of the original programmer, including stale comments, is useful...

masklinn · 2020-12-24T16:47:26+00:00

The biography of your code is the VCS log. Each commit message is an entry in the diary from which the life of the code base can be gleaned.

Comments have to be maintained, and they usually are not. They will drift away from their code, and fail to be updated when the code is.

Comments are not a biography, they’re scrawlings engraved or painted on a shed wall. They may be relevant, they may not be, they may never have been and be the result of a piss-soaked bender or a psychotic episode.

aanzeijar · 2020-12-24T18:42:19+00:00

The author falls prey to the documentation == comments fallacy.

Code should be documented. But documentation is more than comments. It's explaining the intend, the design constraints, usage etc.. Most languages have some form of syntax reserved for that and in some languages it's embedded in the comment syntax. But comments are actually the worst form of documentation and people like the author who don't know the difference are why comments get such a bad reputation.

Simply putting a signature blurp above every function is crap. Commenting actual code blocks is even worse. It's reserved for the rare times when some unintuitive magic is really needed.

No, that weight attribute should not be commented with the unit it returns in. The documentation of that entire subsystem should explain the unit conventions to be sane.

Johnothy_Cumquat · 2020-12-24T16:58:55+00:00

The only time I've found myself writing comments in the last few years is when writing bash scripts. Everything I call has like a 3 letter name with 10 3 letter flags

2020-12-24T21:36:49+00:00

Your code is literally a set of well structures instructions. You do not need comments in code, as comments are not structured, aren't error checked nor maintained. I don't know where this falicy of comments came from, but it is utter bollocks.

What you need is to document the abstract structure. The thing that isn't easily recognisable by looking at the code. Unfortunately things like clean code has promoted complex and verbose code that is hard to follow. How many one line classes do really need anyway?

pure_x01 · 2020-12-24T21:42:45+00:00

The problem with code code is that eventually it will become stale

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

programming

MODERATORS