> code comments document the why, not the how While I do agree with this since thoroughly reading the code itself tells you the how I find comments that tell m

> code comments document the why, not the how While I do agree with this since thoroughly reading the code itself tells you the how I find comments that tell me what it does to be just as helpful as telling why it does it. I used to fall into the self-documenting code camp back when I programmed in Objective-C and long descriptive names with named parameters made it read like English but as I've read more code in more languages I actually prefer shorter names supported with code comments that tell me clearly in English what the code does. For instance earlier today I was reading some of the source code in fossil-scm in the check-in.c file. In it there was a function that was simply named `locate_unmanaged_files`. If there wasn't a detailed comment preceding that function I would have assumed it merely found the files and reported on them directly but after reading the comment explaining what it did I realized it stores the files in a temporary SQLite table, after reading that I learned that "locate" had a wider meaning then to just find it and return it but it rather meant that it is now located for any part of the system to find in the database. It would have taken careful reading of the code to have realized this and it helped me to better focus and understand the code I was reading.