Why did the devil come up with javadoc

It is believed that a good program should be well documented.

SUN even came up with a special javadoc format - “a standard for documenting Java classes”. In my practice, it was a completely common occurrence when some code did not go through the Code Review, because some methods had no comments in it.

I argue that this approach is outdated, and today I will tell you why comments are evil.
')

Life example

This is a real code, written in 2010 by a quite diligent programmer who was not lazy and wrote a comment to his method. Satisfied with myself, but I went to pour myself a cup of coffee from the apparatus, but let us see for now what we have here.

public class AddressUtil {
/**
* Format string as address , expected input
* format:"EE ; ;Tallinn;Narva mnt;120B;831;10127"
*
* @param flatAddress
* @return Formatted address
*/
public static String toString(String flatAddress) {......}
}

Fine! We have a well-formed javadoc commentary from which a special program can generate HTML documentation. It is easy to understand from it what (theoretically) this method does.

Where is the devil hiding?

But where are the little things the devil hid in? And here they are:

• Very soon, this documentation will become obsolete , because another developer will come and change the code, but will forget to change the documentation. It may even be the same developer, because while he was queuing for coffee, it occurred to him that he forgot to process one rare case. When he returns, he will add the necessary IF to the code, but will forget that he already has a javadoc that needs to be maintained .
• The documentation does not describe a lot of cases: how will the method behave if the input is null or an empty string? What if there is a house number in the address, but no apartment number (that is, the bourgeois occupied the whole house)? What is the empty parameter between “EE” and “Tallinn”?
• There is no word in the documentation that this method returns .
• There are three extra lines in the documentation: "*", "@param flatAddress" and "@return Formatted address". Just think: they occupy most of the documentation, and they are absolutely useless!

Magic

And now let's play wizards and turn some colored pieces into a garland. Let's make some magical passes. Sim-salyabim, Akhalay-makhalay, Lasyki-masyaski ...

• Pass number 1: Everything that is written in red , turns into the name of the method: toString -> formatAddress.
• Pass number 2: Everything that is written in blue is transferable to a unit test .
• Pass number 3: (my favorite) All the text written in green - ... correctly, erasing. Forever and ever. Do not feel sorry for him, he was born in vain!

What we got in the end?

public class AddressUtil {
public static String formatAddress (String flatAddress) {......}

@Test public void testFormatAddress() {
assertEquals("Narva mnt 120B-831 10127 Tallinn",
AddressUtil.formatAddress("EE ; ;Tallinn;Narva mnt;120B;831;10127"));
}

}

How is the new version better than the old one?

• It is stupidly SHORT: there were 8 lines, it became 4.
• This test will never become obsolete, because it will run automatically every time you build the project, and if the programmer changes the code and forgets about the method, it will immediately pop up.
• You can describe all the rare cases: empty lines, missing parameters, invalid values, etc.

In a word,

GOOD NAME + TESTS = DOCUMENTATION

or rather, “run documentation” (executable documentation), that is, documentation that can not only be read, but also “run”, automatically checking that it is still adequate.

They say that Confucius had a poster over his bed:

Convert comments to executable documentation

Afterword

I am only afraid that our valiant programmer, having returned from the kitchen, will not understand the focus, because he did not see our magical movements. He will demolish the tower from the mere fact that his comments are SOMETHING POTTER, and he will try to find us and destroy for such subversive activities. And his coffee in the meantime cool. Well, and that is not bad: after all, coffee, they say, is harmful. So, we did one good thing today.



UPDATE
In the comments a lot of indignations fell over the fact that it is inconvenient to use open-source libraries without documentation. This article is not about export code. It is about the “internal” code that you and your colleagues write, and you and your colleagues will be the only ones that you have to change several times. In the "export" code, everything is different - there is certainly a need for documentation, but it is necessary to monitor the state separately. You do not need to change it, but only to read. This is a completely different story.


Andrey Solntsev