Hacker News Reader

One thing I've done in the past is put comment "tours" in the code so you can follow with your IDE's search. Each comment has the name of the specific tour, a number, and the tour guide's blurb. This lets the visitor follow a nice sequence, across different files if necessary... Sort of like the inverse of literate programming

View on HN

I'm all for using comments, but you have to be on a team that's on board with them. I've joined more than one team that adopted the "the code should be its own documentation bruh" attitude, as if comments get in the way such that your IDE can't just collapse them all if you don't want to see them. In that case, I'm usually forced to give up. Lesson learned – always ask for the engineering team's stance on comments when interviewing!

Reply on news.ycombinator.com