3 ms·

I personally don't care what anyone says, I use comments and doc comments ALL OVER the place; I do it in reverse, though. I write a list of steps for the applic

by ok_dad 2y ago

I personally don't care what anyone says, I use comments and doc comments ALL OVER the place; I do it in reverse, though. I write a list of steps for the application as comments, a rough draft at first, then as I develop the code I take the big steps and split them into little steps, sometimes removing the original comment and sometimes not, and I continue to split comments into smaller steps until I have nearly a complete algorithm. Then I just code the logic in there. I normally will code from the outside in, so I'll also be writing code as I do the comment-splitting stuff. Sometimes I get off on a tear and I code a bunch of stuff at once, but then later I go back and comment it down to a level that I think most of you would find annoying. Every function and variable has a comment about what it does, even the `deg_to_rad` function has a comment `"""Converts degrees to radians."""`. Why not, storage is cheap! I know most people don't like it, and that is fine, they can deal with it! I they don't want to see my comments, they can remove them from their version of my code with a script, and if my co-workers and boss don't like them they can remove them in a code review! However, I can say that I enjoy reading my old code way more than I enjoy reading other's code which have zero comments. I work in Python, so a lot of the simple non-algorithm code (boilerplate stuff for apps, like flask APIs for example) is mostly "self-documenting" since the old saying goes, "write some pseudo-code and 95% of the time it runs in Python." The most important comments are sometimes on the boilerplate stuff because that's where a lot of changes happen versus the algorithms where I find there is a lot more wholesale rewriting in my industry. I will always love comments and doc comments!

buggy6257 2y ago
> I know most people don't like it, and that is fine, they can deal with it! I they don't want to see my comments, they can remove them from their version of my code with a script, and if my co-workers and boss don't like them they can remove them in a code review! It was all great until you got here. This is a big red flag for me for a teammate.
- ok_dad 2y ago
  Well I don’t think we’ll end up being teammates, and I haven’t had issues before :)
gleenn 2y ago
Comments are great when they are well maintained. But for every codebase that isn't basically some open source software where the eyeballs-reading to comment-maintaining ratio is really high and people spend the time, everyone eventually forgets and/or is too lazy to maintain them. It can be almost as much work updating the comments as adjusting the code a lot of the time. So the ground truth reality is that comments are usually "lies waiting to happen". Eventually, the comments and the code won't be in sync, and this can be potentially worse than having either bare, uncommented code, or better, having actual automated tests that show intent. The tests mostly can't lie, otherwise you wouldn't have merged them presumably. If you show me a bunch of decent tests laying out how the code is intended to be used, that is what I want to see. Because it is explanatory AND it is nearly guaranteed to be truthful.
- rich_sasha 2y ago
  I never found that to be a problem in practice. Yes, comments do get slightly out of sync, and not always corrected. But typically enough comments are correct that you can make sense of the whole thing, and can even fix the comments then. By contrast, I have really never seen truly self documenting code. The comments may be up to date by virtue of not existing, but the end result is just more confusing. YMMV
  - awfulneutral 2y ago
    Same, my coworker used this argument when I tried to get them to write more comments. The number of hours I've wasted due to there being no comments at all is way, way, way more than the very small number I've wasted due to a no-longer-accurate comment. And I usually find that people who write self-documenting code choose variable/function names that might make sense to them at the time, but are vague and confusing to me when I need to read the code.
    - bottlepalm 2y ago
      Same here as well, I hear this argument a lot, but have yet to see a comment I didn't appreciate. And if there's something wrong with the comment, fix it! Self documenting code is a joke.
AcerbicZero 2y ago
Hah, this is me :) Half the time I start by just writing comments explaining what I'm about to try and do, then I go back and add comments about how things did not go as expected, and what I had to do to get it to actually work. Super helpful 5 weeks later when I have to actually see it again.
slaymaker1907 2y ago
I don't think doc comments are warranted in every case and definitely don't think you need to document every single parameter, return value, etc. for every single function, but they sure do come in handy for complicated APIs.
autoeroticdang 2y ago
[flagged]
lifthrasiir 2y ago
I also tend to do so but only for top-level constructs, where such comments are most useful. I think I do so because I like to conceptualize entirely within my mind; I found it rather slow to experiment with various design choices by actually writing them down, at least initially. So I necessarily have to document these design choices once they are settled (as others don't yet have access to my mind :-), while I expect details become much clearer after others also have conceptualized them to their minds. This approach does have a downside of making it possibly harder to read when such conceptualization couldn't be done for any reason, so I do additional tweaking to maintain the baseline readability to the minimum required.
bottlepalm 2y ago
Ah yes, Comment Driven Development (CDD), I practice it as well. You start with comments of how you want things to work, and fill in the code. It's a perfect combination of why/how and communicates to the next developer the high level thought process behind the code perfectly.
phito 2y ago
You're wasting so much time doing this... Nobody will ever read 99% of it. Then the comments will get out of date and it'll end up worse than having no comments.

by ok_dad 2y ago

buggy6257 2y ago

> I know most people don't like it, and that is fine, they can deal with it! I they don't want to see my comments, they can remove them from their version of my code with a script, and if my co-workers and boss don't like them they can remove them in a code review! It was all great until you got here. This is a big red flag for me for a teammate.

ok_dad 2y ago
Well I don’t think we’ll end up being teammates, and I haven’t had issues before :)

gleenn 2y ago

Comments are great when they are well maintained. But for every codebase that isn't basically some open source software where the eyeballs-reading to comment-maintaining ratio is really high and people spend the time, everyone eventually forgets and/or is too lazy to maintain them. It can be almost as much work updating the comments as adjusting the code a lot of the time. So the ground truth reality is that comments are usually "lies waiting to happen". Eventually, the comments and the code won't be in sync, and this can be potentially worse than having either bare, uncommented code, or better, having actual automated tests that show intent. The tests mostly can't lie, otherwise you wouldn't have merged them presumably. If you show me a bunch of decent tests laying out how the code is intended to be used, that is what I want to see. Because it is explanatory AND it is nearly guaranteed to be truthful.

rich_sasha 2y ago
I never found that to be a problem in practice. Yes, comments do get slightly out of sync, and not always corrected. But typically enough comments are correct that you can make sense of the whole thing, and can even fix the comments then. By contrast, I have really never seen truly self documenting code. The comments may be up to date by virtue of not existing, but the end result is just more confusing. YMMV
- awfulneutral 2y ago
  Same, my coworker used this argument when I tried to get them to write more comments. The number of hours I've wasted due to there being no comments at all is way, way, way more than the very small number I've wasted due to a no-longer-accurate comment. And I usually find that people who write self-documenting code choose variable/function names that might make sense to them at the time, but are vague and confusing to me when I need to read the code.
  - bottlepalm 2y ago
    Same here as well, I hear this argument a lot, but have yet to see a comment I didn't appreciate. And if there's something wrong with the comment, fix it! Self documenting code is a joke.

AcerbicZero 2y ago

Hah, this is me :) Half the time I start by just writing comments explaining what I'm about to try and do, then I go back and add comments about how things did not go as expected, and what I had to do to get it to actually work. Super helpful 5 weeks later when I have to actually see it again.

slaymaker1907 2y ago

I don't think doc comments are warranted in every case and definitely don't think you need to document every single parameter, return value, etc. for every single function, but they sure do come in handy for complicated APIs.

autoeroticdang 2y ago

[flagged]

lifthrasiir 2y ago

I also tend to do so but only for top-level constructs, where such comments are most useful. I think I do so because I like to conceptualize entirely within my mind; I found it rather slow to experiment with various design choices by actually writing them down, at least initially. So I necessarily have to document these design choices once they are settled (as others don't yet have access to my mind :-), while I expect details become much clearer after others also have conceptualized them to their minds. This approach does have a downside of making it possibly harder to read when such conceptualization couldn't be done for any reason, so I do additional tweaking to maintain the baseline readability to the minimum required.

bottlepalm 2y ago

Ah yes, Comment Driven Development (CDD), I practice it as well. You start with comments of how you want things to work, and fill in the code. It's a perfect combination of why/how and communicates to the next developer the high level thought process behind the code perfectly.

phito 2y ago

You're wasting so much time doing this... Nobody will ever read 99% of it. Then the comments will get out of date and it'll end up worse than having no comments.