There is a ton of code that only exists because of issues elsewhere in the code. This is the opposite of brilliant code: these are the dirty patchworks, the hacks glueing the whole thing together. Yet often these hacks are necessary, at least until some bug is fixed elsewhere.

Clear, self-documenting code is great but it can't capture that holistic insight into what the whole program is doing. It can't capture context, because the whole point of clean refactored code is to be as context-free as possible.

Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequences.

As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947

It's also only possible if the code is thought of as a text and is proofread/edited rigorously for reading. My process is 1) write the code quickly- add comments 2) revise for clarity and efficiency (usually modularity), remove comments as confidence allows. This is where I might get the variable and method names correct for self-documenting code. Usually it takes several passes. But most often, "good enough is good enough" and I leave comments in. Just in case.

> which itself refers to this HN comment

I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better

Also, any non-trivial software project is going to end up needing workarounds for bugs in other software. And you really need to document those. Because otherwise someone is going to remove that second refresh() statement, not knowing that this works around a bug in OS version xyz.

Basically, "IE8 fix"-comments

> There is a ton of code that only exists because of issues elsewhere in the code.

Or sometimes, not even that: issues elsewhere in the system, possibly completely outside of your control (e.g. the language/framework/library you're using, the OS, business requirements, etc).

> Only "brilliant" code ends up needing comments.

Code shows what is being done. Comments should explain why it's being done.

Code shows how it is being done. Comments should explain what is being done.

In some cases it seems that the name of a function takes care of the "what".

That's a really nice approach. Thanks for sharing, I might borrow it sometime!

> Only "brilliant" code ends up needing comments.

Often you have horrible complexity imposed on you from outside -- business rules you're implementing, etc, which are _not simple_. You can write code that encapsulates a lot of that, and even refactor it so you can see _what_ the code is doing pretty easily ... but it's often _very_ valuable to document in a code comment (docstring, JSdoc, etc) WHY it's like that.

Arguably, the comment is not to explain the code, in this case, but rather to explain the twisted bureaucratic logic you're having to implement, so maybe that still counts as "brilliant" code. ;)

Sometimes things should be commented. Like, for example, every time I have to do pointer arithmetic, I make a comment explaining why, because pointer arithmetic is opaque and error prone.

I agree with this. When dealing with a modern programming language, it's just easier to name your functions and variables in such as way that they're readable. It makes sense to document public functions using the language's documentation syntax, if you're writing an API.

I look back at a lot of my old code and even without comments, it's easy to follow the logic because I used sensible names and constructs.

I have the exact opposite experience. If you find yourself annotating your variables and methods with extra adjectives and nouns, your code isn't simple enough. Those explanations go in code comments.

Often it means you can refactor it so that there is only one of any "thing" so there is no need to clarify which version or role this "fooBarThing" is serving to disambiguate it from the other "bazBarThing".

Functional composition and well structured data is the key to this. It's basically halfway to point-free style.

The variable name can just be fooBar, and bazBar, and organized/namespaced such that you could have Thing.fooBar and Thing.bazBar (assuming you want those exposed to the rest of the application).

Readable variable names doesn't mean wordy names. I would avoid using more than 2 words in a variable name.

Good, clear code, with nice names and such shows what the code is doing and how it's doing it. It doesn't tell you anything about why it's being done, or the context of the function within the code.

You're lucky if you're dealing with code that's either small enough or simple enough not to need the added context...or if you only need to read your old code.

I find the better my types are, the less I need to explain. Canonical morphisms generally don't need comments.

Sometimes requirements or quircks of third party library need a comment.

For glue/app/ux code that's mostly autocompleted, sure. But for domain-specific, algorithmic, magic-formula type stuff, comments are sanity made manifest.

For an alternate perspective you might find persuasive, I recommend you read through the following slide deck: http://www.sqlite.org/talks/wroclaw-20090310.pdf. (Relevant part starts on slide 80, but I recommend you start from the beginning for full context.)