Kristian Dupont Knudsen's "
Top Ten of Programming Advice to NOT follow" showed up on my radar in a
couple of
places recently (those links won't always be to the correct page in del.icio.us, I fear).
Most of it is pretty solid, but two of the ten stuck out at me. First, the advice not to "make sure your team shares a common coding standard." Kristian uses a couple of three line functions to illustrate that both are easily read:
public string FormatAsHeadline(string sourceText)
{
string resultCode = "<h1>" + sourceText + "</h1>";
HeaderCount++;
return resultCode;
}
public string format_as_headline (string source_text) {
string result_code="<h1>"+source_text+"</h1>";
headerCount++;
return result_code;
}
Of course, just about any three-line method will be easy to read. And given that we strive to keep methods short, do we really need coding standards for a team?
I think they are still valuable. Perhaps it is true that in short methods we can read and understand just about anything (minus the
golfing). But if you have some methods named in camelCase, some under_scored, or even SoMeMiXedCasE, it becomes difficult to remember the method name when you are using it in another file. Another issue arises with mixins or long files, if you don't have a convention it forces you to remember more than is necessary just to use a variable or method.
Of course, a good IDE (with a suitable language) can help with these, but it is still an issue or annoyance, and that presupposes you've got support for intellisense in the first place.
The second one stuck out at me because I strongly agree with it: You don't need to "write lots of comments." In my view, comments generally clutter the code and make it harder to follow (if you've got useful names for identifiers). I know it's largely a matter of preference, but Jef Raskin over at ACM Queue supports a
documentation-first style of development (thanks to
Reg for this one too), saying "That we use escape characters to 'escape' from code to comment is backwards. Ideally, comment should be the default, with a way to signal the occasional lines of code."
The best argument made in the article in favor of this (in my opinion, of course) is that "good documentation includes background and decision information that cannot be derived from the code." It is true that design decisions should be documented, but unless it is more complex than the simplest thing that could possibly work, there's no need to document it. And the fact is, most code is glaringly straightforward. In any case, there is certainly no need to have that sort of comment of the obvious littering the code and taking your eyes off of what is actually doing the work.
Just my two cents on a couple of issues. What do you think?
Hey! Why don't you make your life easier and subscribe to the full post
or short blurb RSS feed? I'm so confident you'll love my smelly pasta plate
wisdom that I'm offering a no-strings-attached, lifetime money back guarantee!
Leave a comment
The argument made against coding standards is specious but a common argument nonetheless. You're right that small methods are easy to read but the argument here is being made against a very unimportant type of coding standard: whitespace / layout. Consistency is far more important than whether your braces are on line 1 or line 2.
The same is true of naming conventions. Everyone thinks a coding standard needs to mandate naming conventions. In the grand scale of things, naming conventions are unimportant as long as the names are readable and descriptive. Sometimes there good, external reasons for picking a particular style of name (e.g., with ColdFusion you might decide all CFC names should be lowercase to make the code less sensitive to case if you move between Windows and Unix) but even then, the rules are likely to be broad and not particularly prescriptive.
In both cases, consistency is king, not the actual choice you make.
So if those aren't important in coding standards, what is?
Adopting a standardized organizational structure for code - not layout - is the most important aspect of a coding standard, since that helps people find their way around applications. For example, you might mandate a directory structure for types of code components (e.g., MVC per application) or a general ordering of common elements within a file (e.g., constructor first, then public methods, then private methods in a CFC). You get a lot more benefit from design-level standards than from code-level standards (compare the Mach II Coding Standards and general ColdFusion Coding Standards on
http://livedocs.adobe.com/wtg/public/ - the majority of those standards concern organization and design).
Posted by
Sean Corfield
on Jun 18, 2007 at 11:12 AM UTC - 6 hrs
Sean - That sounds like very solid advice. In particular, I agree that "consistency is king" and that whitespace and layout are not super-important, though I think it is still easier to read if you can agree on a convention and stick to it there.
Thanks also for the tip "You get a lot more benefit from design-level standards than from code-level standards." That's something I never really considered when thinking about standards, but obviously there is a ton of benefit to it.
Always good to have the view of an architect! =)
Posted by
Sam
on Jun 18, 2007 at 11:54 AM UTC - 6 hrs
Most of the time, comments aren't for the real developers, they are meant for the people who don't fully know what they are doing and need it because they are clients. You have to document your code until the point its bleeding javadoc to make sure that clients never get confused by why something is doing what its doing.
Posted by JavaDoc King
on Jun 18, 2007 at 01:34 PM UTC - 6 hrs
I agree regarding comments. I hate working with code that's riddled with single line comments that do nothing other than state the glaringly obvious.
Fowler in his refactoring book, states that if you are needing to write large comment blocks in order to explain how something works, you should question how well structured your code is.
Posted by
James Netherton
on Jun 18, 2007 at 04:04 PM UTC - 6 hrs
@JavaDoc King, I disagree. If your code is well-written and names are well chosen, it should be self-documenting. It's reasonable to require architectural documentation but even there, a well-structured application should be easy to navigate (and this is one of the benefits of using standard frameworks).
@James, totally agree.
Posted by
Sean Corfield
on Jun 18, 2007 at 06:41 PM UTC - 6 hrs
