How to write a great comment on codeofaninja.com?

I love to read and respond to great comments from our readers or students. They make codeofaninja.com a better place. I believe it makes both of us a better coder. Before you write a comment, I just want to point out some things about our website.

  • Our tutorials and source codes are provided as is and are meant only for study or reference.
  • We do not provide a service to customize any code.
  • Our topics are limited, we do not cover every possible use-case scenario.
  • We do not provide you with a complete web application.
  • Most of our readers are students wanting to learn or re-learn PHP.
  • Our tutorials are not perfect, suggestion for improvements are always welcome.

Here's what I think you can do to write a great comment.

Read and study the tutorial.

This really should go without saying. Make sure you understand the tutorial you're going to comment on, and that you fully comprehend my intent. Of course, if you have questions, then those are perfectly acceptable to include in your comment on the post. They may even start a conversation with me and other members of our community.

Add something to the conversation.

Often I will read a comment saying "Wow, great tutorial!" and I appreciate it. But go past that, tell us why you liked our post or highlight issues that I addressed, and add your own take. You don't have to agree completely, and you don't have to stick with my point. If one example I mentioned reminds you of another instance from your own experiences, mention that. But try to avoid simply repeating what others have said.

Wrap the code.

We are using the Disqus comment system. If your comment will contain code, wrap the code inside code tag. This will make your comment more readable and easy to understand. Here's how it should look like. You replace // your code here with your code.

<code> 
// your code here 
</code>

Your comment will look like this:

Also, do not put very long codes, just put the code that matters for your question.

Read the comments that have already been made, if any.

It's really annoying as a reader and a blog owner to have a conversation going - only to have someone come in and ask the same question that has been asked five comments ago, because the writer didn’t read all of the comments. Make sure you’re a part of the conversation, not just a drive-by commenter.

Be helpful.

Most of our visitors are students and people starting to learn or re-learn. I consider myself a lifelong learner. If you feel like you are a more experienced developer, reply to questions where appropriate and give answers. I'm sure many people will appreciate your help and support.

Don't over-promote yourself.

No one likes reading a comment that's blatant self-promotion. We’ve all seen these comments, "Hey Mike, really great thoughts on this topic, I recently blogged about this as well...", then they include a link to their blog (In fact, I often delete these comments if someone attempts to leave one here). Obviously, the only reason they left the comment was to link out to their site. Remember that you aren’t leaving the comment to promote yourself, you are trying to create value for the blog by adding to the conversation. If you’ve done your job, you’ll get promotion as an indirect result of your efforts.

You can disagree, without being disagreeable.

I love it when readers disagree with my tutorials, and challenge my points. I believe this makes us a better coder and communicator. Also, because when you bring in alternative points, that extends the conversation and gives more people a chance to jump and leave their point of view. It will benefit all of our readers and students.

However, always remember that it’s ok to ‘attack’ the ideas, but not the people presenting the ideas. Challenging stances and ideas are fine, but personal attacks add nothing to the conversation, and make you look like a jackass. Not what you want. Feel free to disagree, but don’t be disagreeable.

Attribution

Some ideas from this "How to write a great comment" guide came from Mack Collier and Michelle Waters.