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

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

软件类型（应用程序，库，......）
文档的目标群体（其他程序员，最终用户，......）
贵组织/公司的惯例和品味
等

Javadoc只生成一种特定类型的文档，即程序员使用记录的事物的API文档（这可能包括您未来的自我）。鉴于此，可以给出一些通用指针：

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

我希望这些指针很有用。

文档混乱

1 个答案: