Plain code organized into understandable methods (usually no more than half a page of code), with good naming for variables & method names reduces the need for comments.
It's also easier to scan/read code if there's a minimum of comments in the way.
Plain code organized into understandable methods (usually no more than half a page of code), with good naming for variables & method names reduces the need for comments.
It's also easier to scan/read code if there's a minimum of comments in the way.
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.
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
I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better
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).
Code shows what is being done. Comments should explain why it's being done.
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. ;)
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.
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.
Readable variable names doesn't mean wordy names. I would avoid using more than 2 words in a variable name.
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.