What are the current recommended best-practices for comments.php?

I’m getting ready to submit a theme to the .Org repo and wanted to make sure that everything is in ordnung. One of the biggest holes left in my design is the comments template.

I’ve taken a look at comments.php in a few themes, Twenty Ten chief among them and have come away more confused than when I started. It seems as though (based upon tutorials from Otto, WP Engineer, etc.) the comments template has been simplified, yet when I look at the source to most themes’ comments.php, they are still as convoluted as in the Christian-Montoya-derived days of old.

So help me out — what’s the best way to set up a comments template that will capture the state-of-the art functionality as of WP 3.0/3.1 and yet maintain code simplicity?

You really don’t need much.

A headline with id=comments

<h2 id="comments"><?php comments_number(); ?></h2>

This will be the target for comments_link() in the article loop.

Links for paginated comments.

Usually, I put these links into a function and call the function above and below the comments list:

class TTT_Template {
    function comment_pager()
    {
        if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) )
        {
            ?>
            <div class="comment-navigation">
                <div class="nav-previous">
                <?php
                previous_comments_link( 'Ältere Kommentare' );
                ?>
                </div>
                <div class="nav-next">
                <?php
                next_comments_link( 'Neuere Kommentare' );
                ?>
                </div>
            </div>
        <?php
        }
    }
}

wp_list_comments()

You may use a custom callback function, but you don’t have to. For a theme on wp.org I’d use gravatars in the callback. And I wouldn’t namespace it with my_. 😉

<ol class="commentlist">
<?php
wp_list_comments(
    array (
        'type'     => 'comment'
    ,   'style'    => 'ul'
    ,   'callback' => 'my_comment_callback'
    )
);
?></ol>

As you can see, the type parameter allows you to separate normal comments from pings. See the codex for more information. If you build two separate lists, check get_option( 'default_ping_status' ); to avoid an empty list.

comment_form();

You may use the default settings or add your own filters. I use a custom class to move the textarea to top and rearrange some minor other things.

if ( comments_open( get_the_ID() ) )
{
    locate_template( array ( '/php/class.TTT_Comment_Form.php' ), TRUE, TRUE );
    $ttt_comment_class = new TTT_Comment_Form();
    comment_form();
}

And that’s all.

Complete code

<?php
if ( ! defined('ABSPATH') ) { die ('Nö.'); }

if ( have_comments() )
{
    ?><h2 id="comments"><?php comments_number(); ?></h2>
    <?php
    TTT_Template::comment_pager();
    ?>
    <ol class="commentlist">
    <?php
    wp_list_comments(
array (
            'type'  => 'comment'
        ,   'style' => 'ul'
        ,   'callback' => 'my_comment_callback'
    )
    );
    ?></ol>
    <?php
    TTT_Template::comment_pager();
}

if ( comments_open( get_the_ID() ) )
{
    locate_template( array ( '/php/class.TTT_Comment_Form.php' ), TRUE, TRUE );
    $ttt_comment_class = new TTT_Comment_Form();
    comment_form();
}