CCoding Style - Comment functions and Global data2

Comment functions and Global data ...

A comment that introduces each function sets the stage for reading code itself. If the code isn’t too large or technical, a single line is enough

// random : returns an integer in the range [ 0 ….. r-1]
int random( int r )
{
    . . .
}

Sometimes code is genuinely difficult, perhaps because the algorithm is complicated or the data structures are intricate. In that case, a comment that points to a source of understanding can aid the reader. It may also be valuable to suggest why particular decisions were made.