I'm totally down with the self-describing code vibe. However, I disagree about some of your comment comments :) particularly "Comments get stale".
Many programmers don't comment, they annotate their code. For example the say "Create an XML DOM and load it with the text file cust.xml" when they should actually say "Retrieve a list of my customers". The second version enables someone to understand the intent rather than the implementation.
This kind of comment will rarely get stale, in-fact it will only get stale when you completely change the intent of the code.
Further discussion of this can be found in "Code Complete: A Practical Handbook of Software Construction" by Steve C McConnell."
Cheers LG
Duncan: I see your point - but i think if you get wrong code, comments won;t help there - you'll only get more confused since you won;t know which is right(or is more recent) - the code or the description. Which one would you trust blindly?
If you have a quality control on the code itself (probably by code reviews) then you should be able to trus the comments. This is because a business analyst (or in a really scary set-up, a customer) can read and understand the comments and correct misunderstandings....
Basically it boils down to the fact that developers do not set out to write bugs but they also do not neccessarily have a number of years experience in the business for which the code was written. Therefore they may make assumptions or misunderstand the specification and these gaps in understanding will become bugs in the final code. If there are no comments then these misunderstandings can only be spotted by another developer who is working through the code to fix an error caught in system testing.
Ideally what is needed is a hard link between the specification documents and the source code with configuration management warnings issued if they get out of step....hmm - I see a potential project here.
I see where you're going and I like it :)
A method name like RetrieveCustomerList() is spot on. And if it only contains a few lines of code then that is all that is needed. However, if it does 3 different steps you may wish to comment the intent of each step. We haven't all re-factored mercilessly :)
I actually write my comments before I write my code (as suggested in Code Complete) because it helps you spot logic errors before you've spent the minutes cranking the code.
LG
LG: Well, in that case (of a method with 3 actions) I would go further and call three different methods within that methods - that's how easy it is; each named appropriately scuh as:
ConnectToDB()
GetSuctomerData()
FillXMLFromCustomerData()
and so on...
totally self describing and not one comment to be confused about...
as for writing commments first, I take a different approach. Say I'd start writing such a method - Much like what you do ,only instead of a comment for each action - I write a method call, to something that may or may not already exist. I then proceed to write out the code in the 'ghost' methods. I find it much clearer...
OK I give up :) but I'd still like a comment so I know what "GetSuctomerData()" is doing!!