Agreed: coments suck. The Goal should be to never need to write comments.
FWIW: my solution is to begin with software components. A Component is asynchronous and owns input ports (green circles) and output ports (yellow circles) and may contain other Components or be attached (via the ports and wires) to other Components. My syntax for a Component is a rectangle (as drawn, say, on a physical whiteboard on a wall). Synchronous code cannot be componentized (easily), so I mark synchronous code by putting it into red-coloured rectangles and dropping the red rectangles inside of non-red rectangles (async Components). There are two separable issues - (1) explaining to the machine (aka “computer”) what to do and (2) explaining to other humans why 1 was written the way it was. Frothing aside: operating system processes are simply Greenspun’s 10th Rule bloatware versions of Components. Code libraries are always red-boxed. Lisp 1.5 anonymous functions are less bloatware-y versions of the basic idea. Closures are optimized anonymous functions (optimized along exactly one axis (i.e. the fervent, religious belief that “efficiency” can mean only one thing)). So-called “programming languages” are 1950s IDEs for explaining to stupid machines what to do. Later, these old-fashioned IDEs were given double-duty by conflating the issues of communicating with dumb machines and of communicating with other humans. I find it more fruitful to fully separate these 2 issues, then to drape “syntax” (sugar sprinkles) over the manifestations to provide less-glaring results that cover both issues (syntax, to me is: hybrid diagrams (such as Excalidraw,
draw.io, SVG, etc. that encompass text), i.e. text-based programs are but a subset of less-textual programs)