Commenting code and documenting it has been a topic in these letters already. I linked to resources on how to write docs etc. For the future, this might not be necessary anymore. Because you can have a machine write the comments for you. There is a research project done by Chinese researchers Xing Hu, Ge Li, Xin Xia, David Lo and Zhi Jin named “Deep Code Comment Generation”.

This is their introduction:

In software development and maintenance, developers spend around 59% of their time on program comprehension activities. Previous studies have shown that good comments are important to program comprehension, since developers can understand the meaning of a piece of code by using the natural language description of the comments. Unfortunately, due to tight project schedule and other reasons, code comments are often mismatched, missing or outdated in many projects. Automatic generation of code comments can not only save developers’ time in writing comments, but also help in source code understanding.

You might be wondering what results they achieved:

Here’s a method they used it for (the method is abbreviated and not shown in full in their abstract) public static void sort(Comparable[] a){ int n=a.length; for (int i=1; i < n; i++){ Comparable v=a[i]; int lo=0, hi=i; while (lo < hi) { … } … } assert isSorted(a); }

This method sorts. I deducted that from its name. Now, here is the comment written by a human:

Rearranges the array in ascending order, using the natural order.

And this is what the computer generated:

Sorts the array in ascending order, using the natural order

:spooky:

Another method:

public boolean contains(int key){
	return rank(key) != -1;
}

The human version:

Is the key in this set of integers?

The machine-version:

Checks whether the given object is contained within the given set.

I like the machine-generated more!

If you ever wrote these comments yourself, you know how quickly they are outdated. Having a machine update these on regular intervals make much sense to me!

Here’s the link to the paper: Deep Code Comment Generation

Yours, Holger