> Comments: I find comments, outside of docstrings, a smell.
But is this really the case? I find comments like these invaluable:
/*
* Mark walreceiver as running in shared memory.
*
* Do this as early as possible, so that if we fail later on, we'll set
* state to STOPPED. If we die before this, the startup process will keep
* waiting for us to start up, until it times out.
*/
SpinLockAcquire(&walrcv->mutex);
https://github.com/postgres/postgres/blob/master/src/backend...Part of the job of a developer is to communicate
- domain model (Concepts, Relations between them)
- intention behind the code (Why is this code here?)
- possible pitfalls (I tried this, it does not work because ...)
- limitations (TODO: This special case does not really work, yet)
for your colleagues and future heirs.
How would you ever cramp information like this into variable names and types? (... without introducing so much abstractions that the code becomes unreadable).