On documentation

ramdyne — Sun, 15 Sep 2013 19:34:33 GMT

Andreas Sikkema's law on code documentation:

Once you've properly named every method, function, class or struct, don't document what your code is doing, but why

I can read your code, so what it is doing I can find out myself. Either by reading the code, executing it and watch what it is doing, adding printf()'s everywhere or checking the packets it is sending by using Wireshark. I could even, if I am desperate, run your code in a debugger.

I can't, however, ever find out why in Ctulhu's name you wanted to use Duff's device in that function if you don't tell me!

The first corollary of the above mentioned law is:

Logging why something happens is as important as documenting why code is doing something

ramdyne (Posts about coding)

On documentation