Writing Maintainable Code
Roy posts some great stuff on writing maintainable code. This one in particular just rocks...
<quote>
Self-documenting code is the way to go. I cannot stress this enough. I’ve found, going through 1 year old codebase, that I can easily remember and understand what each method and class does just because the names were meaningful enough to “get” it without trying too hard. Even the new guy got some of these things without me having to explain it to him. The stuff I did have to explain was usually either very complicated and logical, or written poorly enough to not be understood the first time around. The rule of thumb here is “If you need to write a comment on that method it is either too long, or not written in a self documenting way”. (I’m sure I remember writing about this somewhere in my blog, but can’t locate that post or comment….)
</quote>
I've been stressing this point for years now and I can't stress enough how important this is. Writing self documenting code, IMHO, is even more important than documenation itself. Don't get me wrong, documentation is extremely helpful, but if you write "good" code with great naming conventions (i.e. don't ever shorten variable names because you're a lazy typer and name things for what they really are and do) then documentation "should" seem silly. Here's a good example:
Private Function GetUserAddress(ByVal UserID As Guid) As String
End Function
Well what would the documentation say? "Gets the User's Address" Well duh!
Hands down...DO THIS! Thanks for posting your experience up, Roy. Good stuff!