[ntp:questions] NTP Support (Was 'What does "Max Distance Exceeded"...')
hal-usenet at ip-64-139-1-69.sjc.megapath.net
Sat Apr 25 06:46:41 UTC 2009
>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.
More information about the questions