Comment by novocayn

4 days ago

> comment blocks inside codebase

Is vibe-commented a thing yet? :D

Wanted to give fellow readers a good on-ramp for understanding the FTS internals. Figured leaning into readability wouldn’t hurt

For me this makes the structure super easy to grok at a glance

https://github.com/wizenheimer/blaze/blob/27d6f9b3cd228f5865...

That said, totally fair read on the comments. Curious if they helped/landed the way I intended. or if a multi-part blog series would’ve worked better :)

1 comment

novocayn

haute_cuisine 4 days ago

Thanks for the link, very interesting data structure.

I'm wondering is it really worth dumping a general knowledge articles into code comments? To me it feels like the wrong place. Would just the wikipedia link be enough here?

I also notice a lot of comments like this

  // IsEnd checks if this is the EOF sentinel
  //
  // Example usage:
  //
  // if pos.IsEnd() {
  //     // We've reached the end, stop searching
  // }
  func (p *Position) IsEnd() bool {
      return p.Offset == EOF
  }

Is it really necessary to have a text description for a code like "a == b"? It would be really annoying to update comment section on every code change.

This is one of the typical issues when AI creates "code comments", because it always describes "What" is happening. A good comment should answer the question "Why" instead.

For the linked skip list module, a good comment could say why skip list was chosen over b-tree or other data structure and which trade offs were made. AI will never know that.