one thing i love about rust and other strongly typed languages (with sane type systems) is that you can often get most of the information you need about a bit of code just by looking at the types, and in most modern IDEs that’s as easy as hovering over an identifier or even expression

Comments should be metadata and not inline anyway.

Different people reading the same code would expect different comments and even the same person reading for different reasons would need different comments.

For example, do you want to know what the bit of code does? Or how it works? Or what about what to look out for? Or what makes it different from the rest? Or… So many different things comments can tell us, so many different needs for different developers. Of course it’s impossible to agree on a single standard. No one should even bother trying.

Instead we should be looking at comments as a type of annotation that lives outside the code, but then is put back inline by UX when and as needed.

☆ Yσɠƚԋσʂ ☆

The problem here is keeping comments in sync with what the code actually does. This tends to be a problem with all sorts of technical documentation like wikis and other knowledge bases. The more elaborate the comments get the higher the chance that some part of the comments doesn’t get updated when the code changes, and the only thing worse than not having comments is having misleading comments.

Comments can be associated with a single line or code block. The UX keeps track of when a code block has changed and reminds you to update it or marks it as possibly out of sync. Since comments are meta data you can also compare authors of code vs comments for Blame.

☆ Yσɠƚԋσʂ ☆

I’m sure that tooling could help, but I’m just pointing out that making good documentation and keeping it up to date is a non trivial problem.

Post funny things about programming here! (Or just rant about your favourite programming language.)


  • Posts must be relevant to programming, programmers, or computer science.
  • No NSFW content.
  • Jokes must be in good taste. No hate speech, bigotry, etc.
  • 0 users online
  • 1 user / day
  • 3 users / week
  • 19 users / month
  • 99 users / 6 months
  • 1.98K subscribers
  • 350 Posts
  • Modlog