Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Comments on Comments

noncombatant.org

Post reply on HN
Print view View original

11–20 of 50 posts

Re: Comments on Comments

#11

Post by verve_rat »

amadeuspagel wrote: post #3

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

I have wondered what a rich text / markup approach to code would look like. Would remove tabs vs spaces if the code included alignment vs scope nesting marks and the reader could format them however they wanted.

Re: Comments on Comments

#12

Post by arp242 »

kybernetikos wrote: post #6

The advice in 'Replace What Comments With Names' section was just talked about recently here: https://news.ycombinator.com/item?id=37517329 in an article I agree with 'Linear Code Is More Readable'. If you're going to reuse those little tiny functionettes, then sure, it might be worth doing, but to do it for readability is misguided. Comments are a perfectly reasonable way of indicating logical blocks within code.

I've also used scopes for this:

  func DownloadAndVerifyThing(path string) error {
      var url string
      { // Build URL
         ...
         url = [..]
      }
  
      { // Fetch
          ...
      }
  
      { // Verify file.
          ...
      }
  }
I don't do this very often (and I'm having trouble locating an example off-hand, although I'm sure there must be a few in my public code), but it can be pretty useful at times.

Re: Comments on Comments

#13

Post by amadeuspagel »

verve_rat wrote: post #11
amadeuspagel wrote: post #3

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

I have wondered what a rich text / markup approach to code would look like. Would remove tabs vs spaces if the code included alignment vs scope nesting marks and the reader could format them however they wanted.

Yes, related: Tables for conditionals. For example, for routing, have a table where the colums are methods and the the rows are paths. Or for keyboard shortcuts, have a table where the the colums are modifier keys and the rows are the modified key.

Re: Comments on Comments

#15

Post by the_af »

amadeuspagel wrote: post #3

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

Counterpoint: keeping comments in the code results in a simpler format (just plain text, which is battle-tested and requires no special tools or lock-in) and it keeps the comments next to their context.

I find Google Docs comments hard to find and navigate, and usually simply forget to read them. A usability nightmare for me.

Re: Comments on Comments

#16

Post by k2xl »

I typically write comments for "why" rather than "how". Or if I have to make what appears to be a weird hack or decision I put that too.

Another thing I really like to do is put github issues as comments if I am having to do some weird workaround in some API/library that I found from a github issue - i'll put the github issue URL so that way it is easy to see the latest update from that library later on to see if the workaround is no longer needed.

Re: Comments on Comments

#17

Post by nonrandomstring »

Tangential, but see:

https://news.ycombinator.com/item?id=37583258

Explaining "why" is often (revealing) more about how the programmer is thinking at that moment. It reveals hidden or ineffable knowledge about how the coder arrived at that point/design, and may reveal intent not explicit in the code itself.

Mismatches between the declarative and imperative have often been where I've found bugs. Especially in my own code when trying to explain it to myself in a comment opens my eyes to an error.

Those "why" comments are our stories about our code.

Re: Comments on Comments

#18

Post by ibejoeb »

donatj wrote: post #10

In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments. They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.

Bang on. This practice has changed in the hosted, PR-based collaboration world. Instead of embedding this kind of thing in the source itself, it's written up in these constructs that exist outside. Then they go missing or are just undiscoverable, at least until it's too late.

Re: Comments on Comments

#19

Post by majikandy »

I like the idea of comments being impossible and one acts with that in mind. Along with the one about thinking the next person to view your code is a psychopath who knows where you live. Holding those 2 things in mind, you really can have your cake at eat it (too), you can have clean expressive code that covers a lot of the “why” without comments littering the screen.

How are you going to make the code itself scream of its “how and why”? Then failing that you can put a comment if you must.

I have worked with codebase with incredible comments. Changing the code was really hard and laborious and far from a joy to work with. When PRs become back and forth about how to change the wordings of the comments in the code, it is soul destroying, it becomes very time consuming. Like writing a joint novel at the same time as writing the code. Some people like it that way and each to their own, I know I can’t convince them.

Re: Comments on Comments

#20

Post by bluGill »

Missing is one other style of comment: how to use this API. This is not targeted at someone understanding or maintaining the code, but someone outside who just knows (or suspects) they want to use your API without understanding it. While this need not be with the code it generally is better that way because tools can extract information from the code (the comment is before the function foo, therefore it must be about foo, foo takes some parameters with some types - we can link to the documentation for those types...).

This style of comment is only needed if you expect your code to have users who are external and thus don't want to look into the details.

Post reply on HN