3 ms·

I have experienced it, and never have I found it anywhere near as bad as no comments and "self documenting code". IME it's mildly obvious when the comments are

I have experienced it, and never have I found it anywhere near as bad as no comments and "self documenting code". IME it's mildly obvious when the comments are obsolete or out of whack. It's testing one hypothesis. Whereas with no comments, there are basically an infinite number of possible hypotheses as to what the code does.

skohan 4y ago
I think the best solution is having a few tactical comments. Imo the best setup for a project is: 1. Some high-level documentation explaining how the key systems work and interact conceptually, to give context. 2. Comments for anything non-standard (i.e. we're using some weird encoding here instead of JSON because of XYZ reason) 3. Comments for the tricky extra complicated bits For everything else, well-written code following standard conventions and good naming practices is enough. Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code.
- chriswarbo 4y ago
  > Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code. Furthering this, avoid: - "Stringly typed programming": where everything has a static type, but they're all `String` (or `Int`, `Float`, etc. instead of something with domain meaning). This gives very little information to the reader, and makes it easy to mix-up values. - "Boolean blindness": where we query a bunch of booleans to determine what data we can extract, e.g. Result::hasUserId : Boolean Whether this result contains a UserId Result::getUserId : UserId Returns a UserID if hasUserId; otherwise error log("Request came from " + myResult.hasUserId? myResult.getUserId : "anonymous guest") Compare this to e.g. Result::getUserId : Option[UserId] log("Request came from " + myResult.getUserId.orElse("anonymous guest"))
- LorenPechtel 4y ago
  This. I regard comments as something a bit negative. You use them if you have to but you see if you can write the code so you don't need them. If it's internal to my code I can almost always get rid of the comment, I end up with most of my comments referring to external matters.
bobthepanda 4y ago
I think that if you want “what the code does”, detailed description in the commits is much better, since then you can at least see the snapshot with its original context. You can even go through a particular file’s associated changes to see how it’s morphed over time.
scotty79 4y ago
I had the opposite experience. I never read a comment worth reading. Reading code was always strictly better. Truthful and often easier to parse and understand. And with code you can actually converse by putting in breakpoints, disabling parts of it and observing it what it is actually doing, how and infering why. Documentation was always dead almost always outdated prose. Even when it was up to date and accurate I often understood what the person writing a comment actually meant only after I read and understood the code it was referring to.
- rich_sasha 4y ago
  Perhaps it comes down to a preference of reading code depth-first vs. breadth-first. Reading code only is best for depth-first I guess. Suppose function A has a call graph that is 3-6 levels deep, with 3 immediate children. If you want to read it breadth-first, you'll want some context as to what the three children do. If you want to read it depth-first, the comments are somewhat redundant, because you're going down to the source anyway. I rarely have a desire (and even less often a strict need) to understand the whole call graph of a function. If it works fine, tests pass, and I want to understand / change one specific behaviour, I need to grok a slither of the entire possible call graph. Comments help guide where I'm going then. If grokking the whole thing, I see how comments are at best a waste of space.
- mason55 4y ago
  > infering why To me, this is where the most valuable comments are. The more that your code is a representation of business logic, the more you have weird "whys" to fill in. Any kind of plan that involves everyone on the team inferring the same "why" is a terrible plan in my book.

skohan 4y ago

I think the best solution is having a few tactical comments. Imo the best setup for a project is: 1. Some high-level documentation explaining how the key systems work and interact conceptually, to give context. 2. Comments for anything non-standard (i.e. we're using some weird encoding here instead of JSON because of XYZ reason) 3. Comments for the tricky extra complicated bits For everything else, well-written code following standard conventions and good naming practices is enough. Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code.

chriswarbo 4y ago
> Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code. Furthering this, avoid: - "Stringly typed programming": where everything has a static type, but they're all `String` (or `Int`, `Float`, etc. instead of something with domain meaning). This gives very little information to the reader, and makes it easy to mix-up values. - "Boolean blindness": where we query a bunch of booleans to determine what data we can extract, e.g. Result::hasUserId : Boolean Whether this result contains a UserId Result::getUserId : UserId Returns a UserID if hasUserId; otherwise error log("Request came from " + myResult.hasUserId? myResult.getUserId : "anonymous guest") Compare this to e.g. Result::getUserId : Option[UserId] log("Request came from " + myResult.getUserId.orElse("anonymous guest"))
LorenPechtel 4y ago
This. I regard comments as something a bit negative. You use them if you have to but you see if you can write the code so you don't need them. If it's internal to my code I can almost always get rid of the comment, I end up with most of my comments referring to external matters.

bobthepanda 4y ago

I think that if you want “what the code does”, detailed description in the commits is much better, since then you can at least see the snapshot with its original context. You can even go through a particular file’s associated changes to see how it’s morphed over time.

scotty79 4y ago

I had the opposite experience. I never read a comment worth reading. Reading code was always strictly better. Truthful and often easier to parse and understand. And with code you can actually converse by putting in breakpoints, disabling parts of it and observing it what it is actually doing, how and infering why. Documentation was always dead almost always outdated prose. Even when it was up to date and accurate I often understood what the person writing a comment actually meant only after I read and understood the code it was referring to.

rich_sasha 4y ago
Perhaps it comes down to a preference of reading code depth-first vs. breadth-first. Reading code only is best for depth-first I guess. Suppose function A has a call graph that is 3-6 levels deep, with 3 immediate children. If you want to read it breadth-first, you'll want some context as to what the three children do. If you want to read it depth-first, the comments are somewhat redundant, because you're going down to the source anyway. I rarely have a desire (and even less often a strict need) to understand the whole call graph of a function. If it works fine, tests pass, and I want to understand / change one specific behaviour, I need to grok a slither of the entire possible call graph. Comments help guide where I'm going then. If grokking the whole thing, I see how comments are at best a waste of space.
mason55 4y ago
> infering why To me, this is where the most valuable comments are. The more that your code is a representation of business logic, the more you have weird "whys" to fill in. Any kind of plan that involves everyone on the team inferring the same "why" is a terrible plan in my book.