commenting your functions

When writing source code, it's nice to leave some comments, so others can understand what you were thinking. Of special concern is the documentation of public methods / functions -- that is, code that is designed to be used by other people. It's a far cry from Knuthian literate programming, but it's a start...

There are some systems to generate documentation (PDFs, html etc.) from these comments, such as JavaDoc, GTK-Doc and Doxygen. The idea is that your format your comments in such a way that these tools can understand them, and generate documentation from them. The details of this format are remarkably similar, at least between the systems mentioned here. Note that these are for C/C++ and Java; other languages have different systems.

I've found that I am much more likely to properly document my code when I have tools like the once discussed here. They take away enough of the boredom-factor to make me do it.

doxygen

I am mostly familiar with doxymacs, which is the system that adds support for Doxygen in emacs. In practice, this means that in doxymacs-mode, you can go to a function, press C-c d f (doxymacs-insert-function-comment), and a template with the arguments for this functions appears. For example, after doing this for frobnicate_numbers, we get:

/** 
 * 
 * 
 * @param a
 * @param b 
 * 
 * @return 
 */
int frobnicate_numbers (int a, int b);

Now, all we need to do is write some nice comments. Apart from a description and requirements for a and b, we should say something about the return value, if any values need to be freed, exceptions and so on. Note, I usually put the comments in the header file; that way, people can read the documentation by scanning the header files. Some people however prefer to put the comments in the implementation file.

Apart from the doxymacs-insert-function-comment mentioned above, there are also functions to include file comments (C-c d i, doxymacs-insert-file-comment) and others; see the doxygen documentation.

To install doxygen, get the package (for debian/ubuntu users: get the doxymacs-package), and then add to your .emacs:

(add-hook 'c-mode-common-hook
  (lambda ()
    (require 'doxymacs)
    (doxymacs-mode t)
    (doxymacs-font-lock)))

Of course, after nicely commenting your functions this way, you can create documentation for your code. For some example of this, see the KDE API documentation, which uses Doxygen.

I can recommend learning those keybindings; they are great timesavers.

gtk-doc

As an alternative, popular in the GLib/GTK+-world, there is GTK-Doc, which works in a very similar way. It can be a bit tricky to set up, but the integration with DevHelp is very nice -- and DevHelp you can be integrated with emacs. Anyway, GTK-Doc also provides some integration with emacs; so can get this by installing gtk-doc-tools, and then adding to your .emacs (assuming that gtk-doc lives in your load-path, see installing packages):

(add-hook 'c-mode-common-hook
  (lambda ()
    (load "gtk-doc")))

After that you can add comments to your functions with C-x 4 h ('gtk-doc-insert') in the gtk-doc format, which is slightly different from the doxygen one. (Gtk-Doc has special support for GTK/Glib-specifics but that's beyond my scope here...)

/**
 * frobnicate_numbers:
 * @a: 
 * @b: 
 *
 * 
 *
 * Returns: 
 **/
int frobnicate_numbers (int a, int b);

other

Finally, if you're programming Java, you'll be happy to hear that there is specific support for JavaDoc-style comments when you're using the excellent JDE (Java Development Environment). I haven't used it recently though, let alone its Javadoc support. So please refer to the documentation for details.