文档混乱

Question

我渴望成为一名软件工程师，并且我一直在为我的大学学习计算机科学课程。虽然他们教了我们很多在网上很容易学习的基础知识，但我也想学习一些东西，比如常见的文档约定。我敢肯定，一旦我开始学习数据结构等课程，他们就会教授更多关于实际编码的过程，据我所知，这是最重要的部分。但我想尽早开始学习如何正确地做事，所以我正在努力学习如何正确地记录我的代码。

我阅读了有关 javadoc 的维基百科页面，并尽我所能复制它。如果有人可以为我只是为了练习文档而制作的这个简单程序提供任何提示、指示或更正我的文档（甚至代码），将不胜感激。

Transform.java

import javax.swing.JFrame;

/**
 * @author      Nekko Rivera nekkoriv@gmail.com
 * @version     1.0
 * @since       2015-08-9
 */

public class Transform
{
    public static void main(String[] args)
    {
    Gui theGui = new Gui();

    theGui.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    theGui.setSize(600, 400);
    theGui.setResizable(false);
    theGui.setVisible(true);
    }
}

Gui.java

import java.awt.FlowLayout;
import java.awt.event.ItemEvent;
import java.awt.event.ItemListener;

import javax.swing.Icon;
import javax.swing.ImageIcon;
import javax.swing.JComboBox;
import javax.swing.JFrame;
import javax.swing.JLabel;

/**
 * @author      Nekko Rivera nekkoriv@gmail.com
 * @version     1.0
 * @since       2015-08-9
 */

public class Gui extends JFrame
{
/**
 * Generated by Eclipse
 */
private static final long serialVersionUID = 7253493887106168112L;

/**
 * Name displayed on choiceBox for the user to select
 */
String[] portraitNames = {"Default", "Nurio", "Giada", "Triggah", "Spider"};

/**
 * The images that will be displayed upon selection
 */
Icon[] portraits = {new ImageIcon(getClass().getResource("default.png")), new ImageIcon(getClass().getResource("nurio.png")), new ImageIcon(getClass().getResource("Giada.png")),
        new ImageIcon(getClass().getResource("Triggah.png")), new ImageIcon(getClass().getResource("spider.png"))};
/**
 * Allows the user to choose a portrait to display
 */
private JComboBox <String> choiceBox;

/**
 * Prompt for the user to change their appearance
 */
private JLabel promptLabel;

/**
 * Builds the window for the program
 */

/**
 * Displays the image chosen by the user
 */
private JLabel pictureLabel;

public Gui()
{
    super("Transform");
    setLayout(new FlowLayout());

    drawGui();
}

/**
 * Draws the items onto the frame
 */
public void drawGui()
{
    pictureLabel = new JLabel(portraits[0]);
    promptLabel = new JLabel("Change appearance?");
    choiceBox = new JComboBox <String> (portraitNames);
    choiceBox.addItemListener(
            new ItemListener(){
                @Override
                public void itemStateChanged(ItemEvent event)
                {
                    if(event.getStateChange() == ItemEvent.SELECTED)
                        pictureLabel.setIcon(portraits[choiceBox.getSelectedIndex()]);
                }
            }
            );

    add(pictureLabel);
    add(promptLabel);
    add(choiceBox);
    }
}

TLDR：记录是否正确？

Answer 1

确实没有正确的文档编制方法。什么是好的文档取决于很多因素：

软件类型（应用程序、库...）
文档的目标群体（程序员同事、最终用户……）
您 organisation/company
等等

Javadoc 只生成一种特定类型的文档，即 API 程序员使用文档化事物的文档（这可能包括你未来的自己）。鉴于此，可以给出一些一般性的指示：

所有类，从包外部可见的字段和方法必须记录在案。这包括 public 类和 public 以及受保护的成员（字段和方法）。在您的情况下，缺少 public 类的文档。
私人物品和包裹私人物品是否也必须记录在案取决于当地习俗。记录一些东西永远不会错。
方法的有用 Javadoc 文档描述了方法的作用。它也可以描述如何该方法如何做到这一点，但在大多数情况下，对于使用该方法的人来说这并不是真正有趣的，并且也可以使用非 Javadoc 注释进行记录。
文档应该准确无误。如果有前置条件，则应提及（例如，某物不能是 null，数字必须是 >= 0，等等）。如果有特定的极端情况，则应提及。如果方法有副作用，必须注明。

希望这些建议对您有所帮助。

文档混乱

Documentation Confusion

java

documentation

javadoc