Should code comments link to Stack Overflow answers? Let's argue about it

#discuss #programming #documentation #webdev

Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com

Open any mature codebase and search for stackoverflow.com. You'll find a few dozen comments like this:

// Safari doesn't fire 'change' on autofill, see
// https://stackoverflow.com/a/<answer-id>

Some teams love these. Some ban them in code review. Most have never discussed it. I think it's worth arguing about, because the answer affects how future maintainers understand the strangest parts of your code.

The case for linking

It explains the why in one line. The hardest code to maintain is a workaround with no explanation. Why is there a setTimeout(fn, 0) here? Why is this header set twice? A link to the answer where someone diagnosed the browser bug or the library quirk gives the next developer the full context, including the discussion, the edge cases, and the comments saying "this also happens on Firefox".

It's honest attribution. If you copied or adapted code from an answer, the source should be recorded. Content on Stack Overflow is licensed under Creative Commons Attribution-ShareAlike (the exact version depends on when it was posted), and attribution is part of the licence. A link in the comment is the simplest way to provide it.

It's a signal for later cleanup. A comment pointing to an answer from 2014 about an Internet Explorer bug is a flag: this code may no longer be needed. Without the link, nobody knows the workaround was for IE.

Search engines and AI assistants don't replace it. "Look it up if you need to" assumes the next person knows what to search for. The link removes that step.

The case against linking

Links in code rot quietly. Nobody runs a link checker over source files. Answers get deleted, accounts get removed, questions get closed and merged, and URLs change format. When the link dies, the comment becomes a riddle: there was an explanation, and now there isn't.

Answers change after you link them. An answer can be edited, sometimes substantially. The version you read and adapted may not be the version a maintainer reads in three years. The comment says "see this", and "this" now says something different.

It outsources understanding. A link can become a way to avoid writing an explanation. "See SO" is not documentation. If you can't summarise why the workaround is needed in two sentences, maybe you don't fully understand it yet.

Some links are noise. A link to "How do I reverse a string in Python" next to s[::-1] adds nothing. A codebase full of trivial links teaches people to ignore all of them, including the important ones.

Comments aren't the only links that rot. linkbruno.com watches the links in your docs and site and alerts you when one of them breaks.

Where I've landed

I'm in favour of links, with rules:

Explain first, link second. The comment should make sense even if the link dies. One or two sentences on what the problem is and why this code works around it, then the link as evidence.
Link the specific answer, not the question. Use the "Share" link on the answer (/a/<id>), so it points to the content you actually used.
Include a date or a version. "Safari 16 and earlier, Nov 2026" tells a future maintainer when to re-check. It also helps if the answer is later edited.
Use revision links when the exact text matters. Each answer has a revision history; linking a specific revision pins the version you read.
Attribute copied code properly. If you used a substantial piece of code from an answer, the link is the minimum. Check what your organisation's policy says about Creative Commons code in your codebase, because some legal teams have opinions.
Check links in source code occasionally. Most link checkers can read source files if you tell them to. Running one over **/*.{js,ts,py,go} once a quarter costs little, and it's the only way those links ever get checked. Tools such as linkbruno.com and command-line checkers can both do this.

A good version of the example above:

// Safari (<= 16) doesn't fire 'change' when it autofills a field, so we
// also listen for 'input' and compare values. Discussion and repro:
// https://stackoverflow.com/a/<answer-id> (checked Nov 2026)

The cases that start arguments

GitHub issue links instead. Linking the upstream bug report (for example, the browser's issue tracker) is often better than an answer about it, because it tells you when the bug is fixed. But issue trackers move too.
Internal wikis. Some teams prefer to copy the explanation into an internal page and link that. The wiki then rots instead, with fewer people looking at it.
AI-generated code. If a workaround came from an assistant, there's often nothing to link. Should the comment say where it came from anyway?

Why this matters more than it looks

Comments with links are some of the longest-lived links you'll ever write. A blog post gets rewritten or deleted. A function with a clever workaround can sit untouched for ten years, and the link is the only explanation it has. If that link dies, the next person either keeps the weird code forever because they're afraid to remove it, or removes it and reintroduces the bug.

Either way, it's worth deciding as a team rather than leaving it to whoever happens to review the PR.

DEV Community