DON'T Comment Your Code

I added a comment here but then realized it wasn't necessary and removed it

My favourite comments to write: the link to the stack overflow article I stole it from

My mantra is “just because it’s called code doesn’t mean it has to be cryptic”.

I’ve heard this for 50 years. In my experience, comments should (1) identify dependencies that are not apparent, (2) describe reasoning for architectural choices, (3) significantly reduce surprise.

Comments remind me why/how I designed the code after I come back after a year. It saves me loads of time.

The most beautiful code ever read a number of years ago had no comments either. It was a one page beautifully structured utility file, with fantastic naming and nicely sized composable methods. It wasn’t pretentious or trying hard to be “smart”. It was as if the developer had taken great care to speak through the code. I would argue that it crossed over into being a “work of art”. 🌟

Most of my comments serve to warn against an urge someone might get to do X refactoring that seems natural, but that they wouldn't know in advance that it would break Y (performance) requirement, or in order to give more context to why something is done like it is, explaining a conscious decision that was taken in regards to a minor implementation detail. These cases are extremely rare, they don't fit into public interface documentation and are usually one liners.

"This code was hard to write, it should be hard to understand.", always goes down a storm at code reviews.

I write doc comments for the intellisense, but also to write specifications, because it's unruly to leave it only to unit tests. Visually, it's also helpful to see the big blobs of green on the code overview next to the scroll bar in editors like VSCode.

There are 2 types of comments I usually write. #1, API doxygen style comments about the functionality of a function (sometimes add pre, post conditions if not clear) #2, Explaining decisions: WHY I choose that particular solution. Otherwise I try to name variables/functions accordingly.

The one type of comment that is always helpful: reference to external material. That might be the chapter of a standard that you are implementing, or the address of a project where you borrowed the code, or the chapter of a textbook that explains the vocabulary you are using.

Mate, really wish you would drop the clickbait titles.

Comments should tell why a piece of code was written and not what a piece of code does. This function was written to prevent the company from being fined by breaking such and such regulation. For example at one company they had a function for calculating overtime pay in the US. For most states at the time more than 40 hours a week counted as overtime; however, for one particular state over 8 hours in a day counted as overtime regardless of the total number of hours worked for the week. Without a comment explaining this, someone could modify the function thinking that the > 8 hours was a bug and getting the company in trouble with the regulators.

Some of the most beautiful code I've ever seen was uncommented assembler. It was an x86 linker I took over from the author. You could read it like a book, it was so well organized and named. I was the first other person see it and he asked me what I thought. So I quoted a little Keats: "Beauty is truth, truth beauty..."

The comments I like the most are ones that tell me why and where something comes from. So if you are implementing a scientific algorithm writing down what paper you are implementing is REALLY important. Another common one is if you had to do external calculations for something. For example if you have done optimization and profiling to come up with some settings for a solver then it is really useful to write down why those solver settings are used and where the testing was done.

I do agree, that having single line comments in the style 'a + b // sum a and b' is useless, but you can only preach expressiveness with code for so long. There might be complex functionality, a bug, quirky behavior that is easy to overlook or a business decision that is way easier to understand with one line comment than having to read the implementation or that you turn a double take into a single take. Even a '// yes, this could be probably simpler, but it is an implementation detail and idgaf' is ok in my book... If it's stupid and it works, it ain't stupid. For libraries/utilities it is incredibly useful to add doc comments that describe behavior and show how to use the function (even inside the dev team - people come and go, hell, even if you are the only person writing the code), saving you the time that you would have to read the implementation and also help you avoid potential foot guns. Having comments on function parameters about what they do and how they interact with each other is also super useful, saving you the time that you would have to google/read the docs/query an LLM/read the implementation. Documenting code is also a better experience in some languages take the documentation seriously, compiling and executing code snippets to verify that the code in them is correct, so you can have tests in your documentation. Elixir does this and Go does something similar with their exmaples.

I don't write comments in production code 90% of the time because I rarely find a situation where they help describe the code better than the code itself. I write loads of comments for code I share with students because I'm deluded into thinking they'll somehow read them even though they can't be bothered to glance at a textbook or even pretend to be awake during my lectures.

One of my criteria when marking my students' coding projects is 'how easy was it for me to get up to speed as a newbie dev on this project?'. Good comments can make a huge difference, not just for understanding the code, but for getting inside the mind of whoever was writing it.

issue when using abstraction and generic programming. sometimes comment can say what is NOT in the code and WHY. I've seen routine rewritten (in git history) 4 times to be eventually rolled back to the original with the comment like "this approach works, we tried using a common pattern 'x' but it doesn't work for these reason : xxxx

100% agree. A particularly nice feature I like is "doc tests" in Rust, where each code snippet in doc-strings is ran as a test. I think it's really useful for documenting public APIs, as well as ensuring that the documentation examples are in sync with the actual code