Why the devil came up with javadoc

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

    SUN even came up with a special javadoc format , the "standard for documenting Java classes." In my practice, it was completely normal when some code did not pass Code Review, because some methods didn’t have comments on it.

    I affirm that this approach is outdated, and today I will explain why comments are evil.



    Life example


    This is real code written in 2010 by a very diligent programmer who was not too lazy and wrote a comment on his method. Satisfied with himself, but went to pour himself a cup of coffee from the machine, and 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) {......}
    }

    Excellent! We have a correctly formatted comment in javadoc format from which a special program will be able to generate HTML documentation. From it one can easily understand what (theoretically) this method does.

    Where did the devil hide?


    But where are the little things that the devil hid in? And here they are:
    • Very soon this documentation will become outdated , 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 standing in line for coffee, it occurred to him that he had forgotten to handle one rare case. Upon returning, he will add the necessary IF to the code, but will forget that he already has javadoc, which must be supported .
    • A lot of cases are not described in the documentation : how will the method behave if null or an empty string arrives at the input? What if there is a house number in the address but no apartment number (that is, the bourgeois has occupied the entire house)? What is the empty parameter between “EE” and “Tallinn”?
    • There is not a 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


    Now, let's play wizards and turn a few colored pieces into a garland. Let's make some magical passes. Sim-salyabim, Akhalai-mahalai, Lasyaki-masya ...
    • Pass number 1: Everything that is written in red is turned into the name of the method: toString -> formatAddress.
    • Pass number 2: Everything that is written in blue is transferred to the unit test .
    • Pass number 3: (my favorite) All text written in green - ... right, delete it. Forever and ever. Do not spare him, he was born in vain!
    What did we get as a result?
    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"));
    }

    }

    Why is the new option better than the old?
    • It is stupid SHORT: there were 8 lines, it became 4.
    • This test will never become obsolete because it will start automatically every time you build the project, and if the programmer changes the code and forgets about the method, it will pop up immediately.
    • All rare cases can be described: empty lines, missing parameters, invalid values, etc.

    In a word,


    GOOD TITLE + TESTS = DOCUMENTATION,

    or rather, “executable documentation”, that is, documentation that you can not just read, but also “run”, automatically checking that it is still adequate.

    They say that Confucius hung a poster above the bed:

    Convert comments to executable documentation

    Afterword


    I’m only afraid that our valiant programmer, having returned from the kitchen, will not understand the focus, because he did not see our magical movements. The tower will be torn down by the mere fact that his comments SOMETHING NAKED LOSS, and he will try to find and destroy us for such subversive activities. And his coffee, meanwhile, has cooled. Well, that’s not bad: coffee is said to be harmful. So, we did one good thing today.



    UPDATE
    A lot of indignation fell in the comments about the fact that it is inconvenient to use open-source libraries without documentation. This article is not about exported code. It is about the “internal” code that you and your colleagues write, and only you and your colleagues will use, and which you have yet to change repeatedly. In the "export" code, everything is different - there documentation is definitely needed, but its state needs to be monitored separately. You do not need to change it, but only read it. This is a completely different story.


    Andrey Solntsev


    Also popular now: