Why write Javadoc when there are so many programmer requirements

Tight time, heavy tasks, this is the normal programmer friends. A lot of product design seems to have no time limit, the test time depends on the development delivery time and quality, but the boss wants, urgent, can compress only the development time limit. The quality of development seems to have little to do with whether or not you write Javadoc. Javadoc is naturally ignored. Key code comments are not written in methods, let alone Javadoc, and interfaces are not documented. My future self and my current colleagues read that code like a book out of their head. MGB in mind for countless times.

For the sake of my poor colleagues and future self, try to write javadoc and comments. If you really do not write, I can not hit you, after all, can not reach.

It’s not hard to see that Javadoc takes up a lot of space in some of the best source code, and even two-thirds of the entire file. You basically know what this class or method does when you look at the comments, and you know it when you look at the code. All said good source code to write more comments, if you also write a lot of effective comments, is it also more cattle?

How to write the javadoc

This article focuses on some considerations and usage habits when writing Javadoc. The syntax details and how to generate Javadoc are not the focus of this article.

Javadoc official notes

How do I write documentation comments for the Javadoc tool

Requirements for writing a Java API specification

Javadoc general format

  • Note the project

    The readme. md file is usually written in the root directory. Md is becoming standard for programmers, going wherever they go.

  • Annotation package

    Create a new package-info.java file under the package, which can contain package declarations, package comments. First, it’s a Java file, but it’s not a regular Java file. It has a – in its name, which is illegal in javaclass naming. So you can’t create it.

    /** * package-info 

     So there's no inheritance implementation. * The modifier for all attributes is default because it describes the package. * * /      
package com.package;
// Package constant, which allows only intra-package access
class PkgConstant{
    static final String PACKAKGE_CONST="GOOD";
}
Copy the code

  • Annotation class

    In the case of HashMap, which we hate, here’s some code & comments.

    /* * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. * /

package java.util;

import java.io.IOException;
import java.io.InvalidObjectException;
importjava.io.Serializable; ./**
 * Hash table based implementation of the <tt>Map</tt> interface.  This
 * implementation provides all of the optional map operations, and permits
 * <tt>null</tt> values and the <tt>null</tt> key.  (The <tt>HashMap</tt>
 * class is roughly equivalent to <tt>Hashtable</tt>, except that it is
 * unsynchronized and permits nulls.)  This class makes no guarantees as to
 * the order of the map; in particular, it does not guarantee that the order
 * will remain constant over time.
 *
 * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
 * as it is, generally speaking, impossible to make any hard guarantees in the
 * presence of unsynchronized concurrent modification.  Fail-fast iterators
 * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
 * Therefore, it would be wrong to write a program that depended on this
 * exception for its correctness: <i>the fail-fast behavior of iterators
 * should be used only to detect bugs.</i>
 *
 * <p>This class is a member of the
 * <a href="{@docRoot} /.. /technotes/guides/collections/index.html"> * Java Collections Framework</a>. * *@param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 *
 * @author  Doug Lea
 * @author  Josh Bloch
 * @author  Arthur van Hoff
 * @author  Neal Gafter
 * @see     Object#hashCode()
 * @see     Collection
 * @see     Map
 * @see     TreeMap
 * @see     Hashtable
 * @since1.2 * /
public class HashMap<K.V> extends AbstractMap<K.V>
    implements Map<K.V>, Cloneable.Serializable {... }Copy the code

    1. Company, copyright, license, etc.

    2. Class is based on Hashtable and can store null values.

    3. A more detailed introduction to class

    4. Author, date, version, etc

  • Annotation Method

    Look at the HashMap#put method

      /** * Associates the specified value with the specified key in this map. * If the map previously contained a mapping for  the key, the old * value is replaced. * *@param key key with which the specified value is to be associated
   * @param value value to be associated with the specified key
   * @returnthe previous value associated with <tt>key</tt>, or * <tt>null</tt> if there was no mapping for <tt>key</tt>. * (A <tt>null</tt> return can also indicate that the map * previously associated <tt>null</tt> with <tt>key</tt>.) * /
  public V put(K key, V value) {
      return putVal(hash(key), key, value, false.true); / / call putVal
  }

Copy the code
    1. Methods to introduce
    2. @param Parameter description
    3. @return Describes return values
    4. Sometimes the method author and the class author do not agree, but also write author, date, etc.
    5. Method to comment on lines of code//You can

  • Comment Field

It’s easy. Just explain it

  /** * The default initial capacity - MUST be a power of two. */
  static final int DEFAULT_INITIAL_CAPACITY = 1 << 4; // aka 16
Copy the code

Common document markup

Not to mention some common but obscure document tags like @author, @param, @return, and @version.

  • @see reference. This can be followed by links or text. There can be more than one @see in a document, which can appear on a class or method. Here are three common forms:

    1. @see “thing” : A thing is a string with no link. It could be a book or a definition, or something else. Javadoc identifies thing with a double “”. For example, @see “Jin Ping Mei”

    2. @see label : Jump to a URL. The URL can be absolute or relative. Such as:

      Copy the code

    / ** * @see Java */

    3. ** '@see' ** 'package.class#member label', which refers to a valid class or method, is also the most commonly used form. For example: Java / ** * @see String# equals (Object) equals * /Copy the code

  • {@link package.class#member label**}**, pointing to package, class, class member. The usage is similar to @see. The main difference is that {@link} generates embedded links instead of putting links in the “see also” section. @Link is only a hyperlink, while @see is a reference. Usage Examples:

    / * * * {@link Collections#synchronizedMap Collections.synchronizedMap}
*  {@linkConcurrentModificationException} have introduced package, no need to write a package path, direct writing class. * /
Copy the code

  • {@code text**}** : Marks the text as code style text without parsing. Javadoc ultimately generates HTML, and if there is HTML parsed code in the comments, it will be parsed, which is certainly not what we want. Such as:

    / * * * {@code<b>} Javadoc parses to a newline if it is not declared as code. * /Copy the code

  • {@value package.class#field**}**, representing constant value. There are two scenarios,

    1. No parameters, such as:

         /**
     * The value of this constant is {@value}. * /
    public static final String MY_CONSTANT = "GOOD"
Copy the code

    2. The package.class#field argument is the same as @see or @link, except that the field must be constant. Such as

            /**
        * Evaluates the script starting with {@value #SCRIPT_START}.
        */
       public String evalScript(String script) {
       
Copy the code

  • HTML syntax

    Javadoc recognizes HTML code in comments. Common ones are:

    <p> <pre> <tt> <a> <ul>, < I >......Copy the code

conclusion

In the process of programming, there are many details that can be written or not written, such as code cleanliness, such as programming specifications, such as writing comments. It is in the details that you can see a person’s true level. The devil is often in the details. Come on boy, be a code farmer with pursuit, move bricks happily. Give it a thumbs up before you leave.