comments

Don’t let the programming jerks get you down

In the last two days I saw two more examples where programmers on the internet were being jerks (for lack of a better term). In one case, someone wrote that a project needed to be documented better, and Jerk #1 wrote that in his opinion, the code probably needed to be more clear. Um, no, the first person was talking about documentation for newbies trying to learn about the project. That has nothing to do with code internals.

In the second case, a programmer shared some information that he had worked hard on, and Jerk #2 wrote, “Don’t you know about xzy?” It turned out that the first programmer did know about xyz, but that wasn’t even important. The point was that the jerk could have written his question much more kindly (such as, “Hey, do you know about xyz? If so, how does that fit in with your work?”).

As you can gather from these stories, both of the jerks were actually being lazy, and just fired off their comments without putting any thought or research into their statements, like they were saying, “Hey, I’m having a bad day, or I’m just a jerk, so here’s a thoughtless comment on your work.”

The moral of this little post is that (a) for some reason, some people in the world can be real jerks, and (b) don’t let the jerks get you down.

Good code is its own best documentation (Steve McConnell)

“Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer.”

~ Steve McConnell, author of several famous programming books, including Code Complete

Markdown comments syntax: Comments that won’t appear in generated output

Markdown FAQ: How do I create comments in Markdown? Especially comments that won’t appear in the generated output.

Part 1 of my answer is that technically there is no way — or at least no standard way — to create comments in Markdown documents, other than to use HTML comments like this:

Insulting comments

It’s crazy how many people write insulting comments when I make a mistake in a blog post. In the most recent example, instead of someone saying something helpful like, “You have a 1 in this function and it should be a 0,” someone wrote something else that I won’t bother to repeat here. Crazy.

Fortunately Mollom has different options where I can report comments like those as “profane,” “low quality,” “taunting,” or “unwanted.” I used to get upset by those comments, but now I just report them to Mollom, hoping it will help blacklist those people from commenting on my site and other sites.

Play Framework template comments (syntax)

When you want to create Play Framework template comments, use the @* ... *@ syntax. Here's a one-line comment:

@* COMMENT *@

Here's a multiline comment:

@*
 * Four score
 * and seven year ago
 * our fathers ...
 *@

(You can format that however you want.)

You can use comments as the first line of Play Framework templates (before the function declaration):

How to create SQLite comments

SQLite FAQ: How do I create comments in SQLite?

SQLite lets you create comments using two different constructs, either two hyphens in sequence ("--"), or the "/.../" C-style comments. Here are examples of each approach, with the SQLite comments preceding the two database table definitions:

A PHP/MySQL script to query the Drupal comments table

PHP/MySQL FAQ: Can you share an example of a PHP script that is used to query a MySQL database and then loop over the SELECT query results?

This weekend I finally fixed a minor/known bug in my PHP/MySQL script that I use to generate the Drupal sitemap for this website. (A PHP script that queries a Drupal MySQL database.) I like to update the sitemap whenever a blog post has changed, and I had all of that working, except I wasn't accounting for changes due to user comments that are approved.