[dllthomas]

"If macros are used properly, they should make the code easier to read, not harder."

Well, I think macros often play the role of jargon. They let you spell out a particular concept succinctly and precisely and make the whole much easier to follow once you are familiar with the jargon, but people unfamiliar won't fully understand.

Much like jargon in spoken language in any field it can be picked such that those otherwise familiar with the language draw conclusions (that are hopefully correct), or picked so that they recognize that they are unable to draw substantial conclusions (which may be incorrect). There are upsides and downsides to both approaches (which isn't to say one doesn't dominate, but from my limited perspective it's not clear).

I should note that, to some extent, this is true of most kinds of abstraction.

[astine]

I suppose. If you don't know what a for loop does you can't really be expected to use one. But you shouldn't have to understand how a for loop is implemented in order to use it correctly is really my point.

Macros can be used to implement some pretty novel abstractions so there can be some temptation to try to understand them by reading the implementation. However, if an abstraction is novel enough, it really should be documented somewhere very thoroughly.

So, to some degree your analogy makes sense. You can use macros (and functions too, really) to express concepts that are unclear unless you have a better familiarity with the topic or the program in question. But I feel that that's what docstrings are for.

[dllthomas]

All certainly the case. Any sort of jargon should be well defined and well documented. Standardizing on jargon between groups eases transitions between groups, but may mean it fits individual problem domains slightly less well. &c, &c.