I think that conventions and a set of patterns explained (or at least listed) in the wiki/readme of a codebase go a long way. When I'm reading some API, then

I think that conventions and a set of patterns explained (or at least listed) in the wiki/readme of a codebase go a long way. When I'm reading some API, then of course I want a detailed comment for each function and value, including valid/invalid parameters, maybe even some runtime behavior stuff if it's important (like whether some async method may contain some cpu-bound parts) any definitely anything unexpected or deviating from conventions. The conventions part being important because usually I don't have the time to read all the comments and all the documentation, but instead I'm looking for some simple concepts I can learn once and then use to understand most things just by reading the identifiers. If the project is written in a consistent way, it can be pretty large but require very few comments to be understandable. And anyone modifying it will need to know some set of rules for it anyway, so they should be made explicit.