[macintux]

Short functions help here.

If every function is just a few lines long, the comments are easier to keep synchronized, and if a function drops out of service, it should eventually be garbage collected with its now-irrelevant comments.

[emn13]

But what if comments pertain to unexpected states the system as a whole can be in?

Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.

I'm not saying that's a good thing; mind you - but nor is it always trivially avoidable, especially if code needs to be concurrency and/or exception safe -- or in general whenever the statements your function consists of have surprising and opaque behavior based on system state, particularly if said state is hard to grasp due to being implicit or dynamic, or simply large and complex.

[TeMPOraL]

> Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.

If the problem has "hub and spokes" topology, i.e. it's relevant to multiple places in code that all reference a single location, put a comment describing the issue in that single location, and everywhere else put a comment with a reference. //Warning. See comment in [that location].

If there's no single best place for the detailed comment, put it in some design notes file, and put a comment with a reference to that file in all the affected places.

DRY can, and should be, applied to comments as well.

[emn13]

Centralized comment references sounds like a good+simple idea - I'll try to remember it, and hope I never have to of course ;-).

[TeMPOraL]

Yeah, references to a centralized document is such an obvious thing... once you read about it. It's another thing I recently picked up from Ousterhout's book, and looking back, I can now see the places in past codebases where I wish I thought of that myself.

[macintux]

Agreed, but that’s why I prefer writing code that has no global state. In Erlang, for example, it’s unusual (and the language lends itself via pattern matching to having short function clauses).

It gets a little tiresome threading the relevant state to every function that needs it, but it’s worthwhile in the end.

[emn13]

Even a pure function has "state" - namely its (arbitrarily complex) inputs. But sure, it's a little less of a landmine.

The fundamental issue remains that sometimes your knowledge about that state (whether the classical kind or a proper parameter) can be complex and dependent on what happened elsewhere, especially if the codebase your in was grown into that situation, and not designed like that per-se. A comprehensible set of preconditions and postconditions isn't always a luxury you have, certainly not at first.

[tengbretson]

If a function is only a few lines long its action should be entirely documented by its name.

[macintux]

The action, sure, but there’s more context than that in many cases. See my other comment.

https://news.ycombinator.com/item?id=18773167