Reviewing and debugging a lot of code gives you some interesting insight. In the past when I’ve written code comments I’ve often answered what and how.
// Grab the remote content and transform it to JSON
That comment for example is useless. Anyone can read the code and see what it’s doing and how it’s doing it.
// We need to re-fetch the remote content here because our cached version may be stale after a write operation. //We know this by checking the $potentionally_stale_cache variable.
With this comment we know why we’re refreshing the cache and can understand if this code is still needed or might not be because of changing requirements.