For all orders, Magento keeps a Comments History of all activity on that order. This allows an administrator to track changes that have been applied to the order status, as well as to attach comments for internal use or to be sent to the customer. If you are writing a custom extension that modifies orders then it's best to work within this system and to have your code update orders with the results of any processing done on them. This information can be invaluable for debugging and auditing purposes.
It's very easy to add comments to an order programmatically. First, you can use the Magento web services API to add a comment to an order:
// Connect to the server
$client = new SoapClient('http://magento.example.com/index.php/api/soap/?wsdl');
$sessionId = $client->login('username', 'password');
// Increment ID of the order to add the comment to
$orderIncrementID = '100000006';
// Get the current status of the order
$result = $client->call($sessionId, 'sales_order.info', $orderIncrementID);
$status = $result['status'];
// Add the comment
$client->call($sessionId, 'sales_order.addComment', array($orderIncrementID, $status, 'This is a new comment', false));
The sales_order.addComment method takes four arguments. The first is the increment ID of the order to add the comment to - note that this is the increment ID (visible to the customer, 9 digits), not the internal Magento order ID. The next argument is the status of the order ('pending, 'processing', 'complete', etc). Whatever you set this to will become the order's new status, so be careful with this if you don't want to change it. In the code above, we check what the order's current status is and then supply this value as the status argument. The third argument is the comment text, and the last is a flag that determines whether Magento will email the comment to the customer associated with the order. In this example we don't want the comment sent to the customer, so it is set to false.
Comments can also be added from code that uses the internal Magento API directly:
// Increment ID of the order to add the comment to
$orderIncrementID = '100000006';
// Get the order - we could also use the internal Magento order ID and the load() method here
$order = Mage::getModel('sales/order')->loadByIncrementId($orderIncrementID);
// Add the comment and save the order
$order->addStatusToHistory($order->getStatus(), 'Another new comment', false);
$order->save();
The logic here is very similar to the example using the web services API. Again, the first argument is the order status, and we set it to its existing value to avoid changing it. The second argument is the comment text, and the last controls whether to send an email to the customer.
Order comments can record extra information about the status of an order or actions that have been performed on it. An example of where this could be useful is to add a comment to an order when an external accounting or ERP system receives and processes it. They are very easy to add, so it's well worth creating them in your custom code to give administrators a complete history of all actions performed on that order.