PBP: 094 Elucidating Documentation

The Best Practice discussed here is to use short comments at the end of the line to provide extra detail and make possibly obscure code a little clearer.  I think this can be very useful, but I’m not sure it plays well with a 78 character margin as suggested elsewhere, especially if the function involved is complex and you’re more than a couple of tab stops from the margin.

The book has a clear example of code that has nothing wrong with it but is still hard to read, and then adding comments at the end of the lines to make it clearer.  This example is good, and well-chosen, but not everything fits in a handful of words.  I find I wind up using full-line comments instead, because I need the room.

In general, I like this idea, but find it another place where some flexibility is required.  People and tools who cling too closely to the PBP as The One True Way will (and do) complain about this, and I think they’re wrong to do so.  I think writing clearer code is better than following these rules exactly.

For that situation, the book makes a different suggestion, under “Discursive Documentation”, which should work but I have always had problems with.  Mostly problems with other people reading it.  More on that in that Practice.

Leave a Reply