4 ms·

I understand the issue with conciseness and readability. I think comments are underappreciated when writing code: not only can you explain what some code does,

I understand the issue with conciseness and readability. I think comments are underappreciated when writing code: not only can you explain what some code does, but how it does it, and why it does it that way. This doesn't have to be documentation, per-se, but it's quite nice when it is. > Second, new language is really, really, really a lot of work (I know, I spent a year building one) I know what you mean ;P. I'd say writing a programming language compiler/interpreter is probably the easiest thing about making a new programming language. Tooling, adoption, libraries, etc. are the other 99%. > It'd be awesome if more folks invested their energy into improved tooling for existing languages. I agree, but I have two rebuttals for your following point. I'll start with the more logical one: 1. As a hobby project, learning the internals of how a compilation pipeline works is much more fulfilling and generally applicable then wrestling with whatever API a VSCode developer decides to chose. 2. And here's the more irrational one: If Guido just decided to work on tooling for C, we wouldn't have Python. I'm not saying I'm the next Guido (not even close, haha), but there are some language features that I wish were more mainstream, and what's a better way to show that certain features are a good fit for a language than to make a language with those features? To make an omelette, you have to break a few eggs, I guess. (P.S. Golem looks pretty neat, congrats!)

pmontra 6y ago
Comments should explain the why, not the what or the how. Obviusly that are exceptions, almost all of them around the really algorithmic parts of the code, something I have to write less than once per year (backend software is not that clever.) A good choice of function and variable names is usually enough to explain what code does. If it's not enough probably those functions are doing the wrong thing, maybe more than one at once, and must be redesigned.
- slightknack 6y ago
  > Comments should explain the why, not the what or the how. Obviusly that are exceptions, almost all of them around the really algorithmic parts of the code, something I have to write less than once per year (backend software is not that clever.) Although I agree that choosing clear variable and function names is usually enough to explain what code does, I'm just not entirely convinced that concise code becomes harder to read with multiple people or after coming back after some time. I feel that communication and documentation is generally the best way to get someone up to speed. By concision, I mean something closer to terseness or brevity: exactly enough to understand what's going on, without anything superflous. Here's a classical concise python one liner: def flatten_list(t): return [item for sublist in t for item in sublist] This flattens a list of lists into a list. But if you're actually coming back to the code either having never seen this comprehension or forgetting how it works, a little comment never hurts: # iterates through each sublist to flatten a list of lists into a single list Some may say this is redundant, but it's useful in more complex circumstances too. If you're working on a machine learning pipeline, say, it can be a quick way to block out some code. # normalize all the input data # generate embeddings # train until error doesn't improve for 100 epochs # run the net on our test set (This is my third most favorite programming trick: pretending that something exists, then building it out*) These examples are besides the point though. Terse code doesn't have to be illegible or hard to comprehend; it's all about finding that balance: no less, no more. * My second most favorite programming trick is building a small set of tools and using those to redefine the problem. > If it's not enough probably those functions are doing the wrong thing, maybe more than one at once, and must be redesigned. Often I'll come across old code, think, "this can be written much more efficiently if I do it like this" and then half way through refactoring remember that I did it the first way because I already thought through the problem and realized that the first way was better and but wait maybe if I do this then that and so on... It's easier to leave a quick comment just explaining why code is the way it is, which is all I was suggesting.

pmontra 6y ago

Comments should explain the why, not the what or the how. Obviusly that are exceptions, almost all of them around the really algorithmic parts of the code, something I have to write less than once per year (backend software is not that clever.) A good choice of function and variable names is usually enough to explain what code does. If it's not enough probably those functions are doing the wrong thing, maybe more than one at once, and must be redesigned.

slightknack 6y ago
> Comments should explain the why, not the what or the how. Obviusly that are exceptions, almost all of them around the really algorithmic parts of the code, something I have to write less than once per year (backend software is not that clever.) Although I agree that choosing clear variable and function names is usually enough to explain what code does, I'm just not entirely convinced that concise code becomes harder to read with multiple people or after coming back after some time. I feel that communication and documentation is generally the best way to get someone up to speed. By concision, I mean something closer to terseness or brevity: exactly enough to understand what's going on, without anything superflous. Here's a classical concise python one liner: def flatten_list(t): return [item for sublist in t for item in sublist] This flattens a list of lists into a list. But if you're actually coming back to the code either having never seen this comprehension or forgetting how it works, a little comment never hurts: # iterates through each sublist to flatten a list of lists into a single list Some may say this is redundant, but it's useful in more complex circumstances too. If you're working on a machine learning pipeline, say, it can be a quick way to block out some code. # normalize all the input data # generate embeddings # train until error doesn't improve for 100 epochs # run the net on our test set (This is my third most favorite programming trick: pretending that something exists, then building it out*) These examples are besides the point though. Terse code doesn't have to be illegible or hard to comprehend; it's all about finding that balance: no less, no more. * My second most favorite programming trick is building a small set of tools and using those to redefine the problem. > If it's not enough probably those functions are doing the wrong thing, maybe more than one at once, and must be redesigned. Often I'll come across old code, think, "this can be written much more efficiently if I do it like this" and then half way through refactoring remember that I did it the first way because I already thought through the problem and realized that the first way was better and but wait maybe if I do this then that and so on... It's easier to leave a quick comment just explaining why code is the way it is, which is all I was suggesting.