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.

First the interface, then the implementation

Meaning: first ask what, then ask how.

If interfaces are used, and they are used a lot, it helps to write comment in the implementation part as long as the interfaces are not stabilized. This allows for efficient coding the interfaces and testing them by their consumers.

These interface consumers are also the unit tests, which might need a different or even no implementation, depending on which part is tested. Some interfaces are mocked in a unit test and are not concerned by the implementation of that interface. In that development phase the implementation of that interface is not needed yet.

It is a good and efficient practice to first define and write the interfaces, and test them and their uses well, before writing the implementation of interfaces. Changing the interface is changing the contract between a number of parts of the program, and will lead to more time-consuming refactory than adapting the implementation. A modification of the implementation takes only place in one place, and that is in the implementation itself. The components that use the interface are normally not impacted by changes of the implementation of that interface.

Once the interface is well contracted and tested, the comment in the implementing class can be replaced by the implementing code. And then you have of course to focus on the unit tests of that implementation.

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 that would appear 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.