After reading some of David Strawn's project code, I decided I really like the way he comments things. He does stuff like this:
/* Setting up bla bla */
int x = ...
int y = ...
int arr[] = ...
/*******************/
/* Compute such and such */
arr[0] = x + y;
.....
/*******************/
At first I found it kind of strange, but I actually really like this methodology. The result is truly readable code. The /****/ blocks serve to show the end of a particular "logical block" of instructions. This segmentation is way better, in my opinion, than just the sort of side comments you normally see at the end of a sparse number of code statements. I've been using this style for commenting and documentation for the code I write at work (Sandia), and I think I will continue to. When I show it to other people, they seem to be able to follow it pretty easy by virtue of it being segmented into kind of high-level events, rather than just a dense set of program instructions.
No comments:
Post a Comment