
Don't comment your code. Refactor it. - mcrittenden
https://critter.blog/2020/09/15/dont-comment-your-code-refactor-it/
======
jfengel
The most important "comments" in your code are names. Taking a chunk of code
and giving it a name gives you a small bit of free text to explain what it
does. The function signature gives you a few more words to play with: foo(Bar
x) -> Baz is a function that foos a Bar into a Baz. (Another reason why
functions should have as few arguments as you can manage.) A well-named piece
of code will often read almost like natural language text.

People tend to ignore comments anyway. The fewer of them you have, the more
likely they'll take notice of one that's actually important.

------
valand
> Explaining why the most obvious code wasn’t written. (Design decisions)

This is actually the most important thing in this article. The technical why
of things are often overlooked in today's software development. It rarely is
the problem until the original maintainer moves out to other project. Non-
technical contributor sometimes won't or can't be bothered with it because
either it is pretty complex, they have a lot in their plates doing non-
technical stuffs, or both.

While commenting on the what is DISCOURAGED because 1.) comments can be
quickly outdated and they are not tested/compiled 2.) they can be replaced
with self-documenting code, commenting on the why must be ENCOURAGED, unless
the software has a dedicated technical manuals / design document, which is
pretty rare these days.

> The problem with comments is that they have no compile-time check and tend
> to be forgotten. It’s very easy to change your code but forget about the
> comments.

I write a bit of Rust and they have partial comment check on compile time. We
can write example in the comments and they actually runs and get converted
into a documentation. Neat!

------
mariaanton89
agree...

