Comment programming

Comment programming, also known as comment-driven development (CDD) is a (mostly) satirical software development technique that is heavily based on commenting out code.

In comment programming the comment tags are not used to describe what a certain piece of code is doing, but rather to stop some parts of the code from being executed. The aim is to have the commented code at the developer's disposal at any time he might need it. This is especially useful when the requirements change rapidly. In this case they happen to revert to older versions of themselves, thus making the programmer either write the code again, or revert parts of the code from the versioning repository, which would be more time-consuming. With comment programming, when such a request for reverting to an old implementation arises, the developer just comments the current implementation and uncomments the previous. It is advisable to add short descriptive comments to blocks of commented code.

Practical uses

Creating stubs

A related, but separate, more practical use of comments is for creating stubs with comments describing a feature (usually using special tags) ahead of future development of that feature. For example, this programming process can be used for prototyping a new design pattern. This is done by creating a new structure of classes or functions without any implementation, and adding the implementation at a later date.

Pseudocode Example:

function onClick()
{
   // This is where we handle mouse click.
   // The result of this function is that a button will be highlighted.
}

As you can see in the example, there is a structure around a click event handler. However, comment programming is used instead of a real implementation. The idea is that many functions can be written like this, and then the design can be reworked and revisited without having to refactor a lot of source code.

Programming by example

A lot of source code examples are found on the Internet, and a lot of those examples are re-used.

It makes perfect sense to add a comment containing a link to such a used example.

It is also a kind of respect to mention the original author of the example that you use in your code.

Support of the human species

As developers are humans, they tend to forget things. Commenting your source code helps to remember things. A human's brain is not made for remembering things but rather for thinking. Comments are especially interesting to indicate todo's, ideas for enhancements and refactory candidates.

The comments with todo's are especially interesting for features with lower urgency that can be implemented in a future release, but that must not be forgotten.

Example of a todo in .net C#, that we would otherwise probably forget in the next release. This todo also mentions why we should present a splash screen in this specific case. We want to give the user feedback that the application is starting.

public static class Program
{
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    [STAThread]
    private static void Main()
    {
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);

        // To Do : Show a splash screen.
        // The initialization of the main form takes some time, and the user should know that the application is starting.

        Application.Run(new MainForm());
    }
}

All things change

The evolution of your source code is as much of importance as the code itself. In a living application the source will change and evolve.

A comment can contain a reference to a change request, an issue, an incident or a problem. It can be a change from the past or a change to be developped in the future. A lot of these changes and fixes are not analysed or designed as deep as a normal release is, let alone that those changes are not very well documented.

These changes lead to riscs and responsability discussions, and the least you can do as a developer is to document this in the source code.

A change or fix can lead to commented source lines. Those commented source lines should be documented with a reason why and some kind of reference to a request.

Having such indications available in the source code helps to understand the evolution of the code, and the reason behind decisions and code changes. Decisions of Business and managers are not always very clear. It helps to prevent contra-productivity by rolling back improvements that have a reason to exist.

As normally the source code is saved in a versioning system, this is a very robust way of documenting changes in the code.

Generation of source documentation

Comments with tags can be used for generation of documentation of the source code.

Some of these tagged comments are even generated by the development environment.

Example in .net C#, indicating the main entry point of an application:

public static class Program
{
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    [STAThread]
    private static void Main()
    {
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new MainForm());
    }
}

Explaining the why

A comment should not repeat what the code does, but it should rather tell why something is written in that specific way.

The why can be interpreted here on different levels:

• Why is that part of the source code written like that; what reference or example was found to do it like this
• Why some manager decided to do it like that and instructed you to do it like that
• Why a part of the code had to be changed; what was that change request, incident or problem

Generated comment

Modern software development environments do generate comments in generated code. Generated comment helps you to understand why certain parts are generated in such a way, and indicates you where and what action is needed.

In fact the modern software development environments do promote comment-driven development. It is not that satiric at all.

Popular culture

MSDN Sweden produced a video for April Fools Day 2010, where they satirically presented CDD as if it was a serious methodology.