November 6, 2008

Do not comment code!

Commenting code is the worst practice promoted by "wannabe smart" books about software engineering. Joshua Block in his How to Design a Good API and Why it Matters keynote notes that code should read like prose and shows the good example:

And I completely agree with this statement. Thus good code is self-explanatory and does not require comments. On the other hand comments will never rescue bad code. Sure, we can use something like "TODO: I will fix this dummy trick in the next iteration", but no more than it.