Thoughts? It does feel like there's a lot of things you can do in comments that would be impossible or impractical to do in names alone, even outside of using comments as documentation. There's certainly much more information that you can comfortably fit into a comment compared to a name.
Funny story: the other day I found an old zip among my backups that contained the source code of game that I wrote 23 years ago. I was just learning to code at the time. For some reason that I forgot, I decided to comment almost every single line of that game. There are comments everywhere, even for the most obvious things. Later on, I learned that an excess of comments is actually not considered a good practice. I learned that comments might be a code smell indicating that the code is not very clear. Good code should be so clear, that it doesn’t need comments. So I started to do my best to write clear code and I mostly stopped writing comments. Doing so only for the very few parts that were cryptic or hacky or had a very weird reason for being there.
But then I found this old code full of comments. And I thought it was wonderful. It was so easy to read, so easy to understand. Then I contrasted this with my current hobby project, which I write on an off. I had abandoned it for quite some months and I was struggling to understand my own code. I’ve done my best to write clear code, but I wish I had written more comments.
And this is even worse at work, where I have to spend a ton of time reading code that others wrote. I’m sure the authors did their best to write clear code, but I often find myself scratching my head. I cherish the moment when I find some piece of code with comments explaining things. Why they did certain things, how their high level algorithm works, what does this variable do, why I’m not supposed to make that change that looks like it will simplify things but it will break a corner case.
So, I’m starting to think that this idea that comments are not such a good practice is actually quite bad. I don’t think I can remember ever reading some code and thinking “argh so many comments! so noisy” But, on the other hand, I do find myself often in the situation where I don’t understand things and I wish there were some more comments. Now I’m trying to write comments more liberally, and I think you should do the same.
I guess that’s a generalization of the op’s idea.
Just finished "version 0" for a very simple programming language yesterday, and I'm looking to work on "version 1" this weekend. Rust is truly fun to program in... although writing all the tests was not a very fun experience. But doing the work for that meant I was guaranteed to have a reasonably good grasp of the semantics by the time I finished.
Since it's Rust, there's no garbage collector -- heck, for this particular language, there's not even any memory allocation after startup. Instead you get a giant global array of "memory" to work with. The only data type is the 32-bit integer (and thus, using UTF-32 for strings is actually the """correct""" choice for this language). I'm using a vaguely Lisp-like syntax that revolves around
{[a tree] formed from (brackets and whitespace)}... which was probably slightly easier to parse than more traditional syntax, but Rust's current lack of pattern matching "through"Vec(for example, letting you extractefrom{a b [c (d e)] f}in one step) didn't always make it feel that way.Nest up: adding while loops, exponentiation and bitwise operators, and most interestingly, string and character literals. (The char literals would just evaluate to their character codes, and string literals would only be usable in a specific write-to-memory construct.) And also expanding the standard library. I'd say "version 1" would really be the more properly "complete" version of the language. I also want to do a functional programming variation (ditching the global memory in favour of reference counted cons cells), and also the whole language is kind of just a stripped down version of another much bigger language half-formed in my head, but that's all probably for... not this weekend, at any rate.