>The programmers think it's obvious. It's not! I can see that the code >swaps the positions of the two bytes in a sixteen bit word. If you >don't include a comment explaining *why* you are swapping the bytes it >makes the code extremely difficult to understand. It may be obvious to >you that two bytes are being swapped to put them in "network order" but >it certainly is not obvious to the reader.
I agree that comments/documentation are important, but I think you picked a bad example. A good name for the macro that does the byte swapping is all the documentation that I want for that case. One of my gripes about some code is that it's full of useless comments that I have to wade through to find out what's really going on. I suppose they are helpful if you don't know anything about the code you are looking at, but some context is assumed. An occasional paragraph explaining the big picture is much very valuable. So are notes about anything that is tricky. -- These are my opinions, not necessarily my employer's. I hate spam. _______________________________________________ questions mailing list questions@lists.ntp.org https://lists.ntp.org/mailman/listinfo/questions