About maintainable code

My blog has moved.
You can view this post at the following address:
http://www.osherove.com/blog/2003/7/3/about-maintainable-code.html
Published Thursday, July 03, 2003 11:35 AM by RoyOsherove
Filed under:

Comments

Thursday, July 03, 2003 12:56 AM by londonGeek

# re: About maintainable code

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
Thursday, July 03, 2003 1:02 AM by Duncan

# re: About maintainable code

Comments only get "stale" because the compiler is seen as the final arbitrator of the developer's work rather than a code review. In my apps I comment often but make sure that the comments are updated with the code...

Other language neutral coding techniques are in: http://www.merrioncomputing.com/Programming/7Secrets.htm

One of the problems with self describing code is that if the code is wrong the description is also wrong. Sometimes it helps to have a description of what the code is supposed to do so that you can look at it and see what it is doing and correct any inconsistency.
Thursday, July 03, 2003 1:09 AM by Roy Osherove

# re: About maintainable code

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?
Thursday, July 03, 2003 2:01 AM by Duncan

# re: About maintainable code

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.
Thursday, July 03, 2003 2:06 AM by Duncan

# re: About maintainable code

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.

Thursday, July 03, 2003 2:14 AM by Roy Osherove

# re: About maintainable code

I see where you're going and I like it :)
Thursday, July 03, 2003 2:15 AM by LondonGeek

# re: About maintainable code

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
Thursday, July 03, 2003 2:20 AM by Roy Osherove

# re: About maintainable code

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...
Thursday, July 03, 2003 2:46 AM by LondonGeek

# re: About maintainable code

OK I give up :) but I'd still like a comment so I know what "GetSuctomerData()" is doing!!

Thursday, July 03, 2003 3:36 AM by Roy Osherove

# re: About maintainable code

Heh. You're right. It's not a good method name.
Thursday, July 03, 2003 7:35 AM by TrackBack

# ISerializable

ISerializable