Java 文件混乱

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

我阅读了关于javadoc的Wikipedia页面，并尽力复制它。如果有人能为我的文档（甚至代码）提供任何提示、指针或更正，我将不胜感激

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);
    }
}

导入java.awt.FlowLayout；
导入java.awt.event.ItemEvent；
导入java.awt.event.ItemListener；
导入javax.swing.Icon；
导入javax.swing.ImageIcon；
导入javax.swing.JComboBox；
导入javax.swing.JFrame；
导入javax.swing.JLabel；
/**
*@作者Nekko Riveranekkoriv@gmail.com
*@version 1.0
*@自2015年8月9日起
*/
公共类Gui扩展JFrame
{
/**
*由Eclipse生成
*/
私有静态最终长serialVersionUID=7253493887106168112L；
/**
*选择框上显示的名称供用户选择
*/
字符串[]人像名称={“Default”、“Nurio”、“Giada”、“Triggah”、“Spider”}；
/**
*选择后将显示的图像
*/
Icon[]肖像={new ImageIcon（getClass（）.getResource（“default.png”））、new ImageIcon（getClass（）.getResource（“nurio.png”）、new ImageIcon（getClass（）.getResource（“Giada.png”），
新的图像图标（getClass（）.getResource（“Triggah.png”）），新的图像图标（getClass（）.getResource（“spider.png”））}；
/**
*允许用户选择要显示的肖像
*/
私人JComboBox选择框；
/**
*提示用户更改其外观
*/
私人JLabel promptLabel；
/**
*为程序生成窗口
*/
/**
*显示用户选择的图像
*/
私人JLabel pictureLabel；
公共图形用户界面（）
{
超级（“转换”）；
setLayout（新的FlowLayout（））；
drawGui（）；
}
/**
*将项目绘制到框架上
*/
公共图书馆（
{
pictureLabel=新的JLabel（肖像[0]）；
promptLabel=新的JLabel（“更改外观？”）；
choiceBox=新的JComboBox（名称）；
choiceBox.addItemListener(
新的ItemListener（）{
@凌驾
公共无效itemStateChanged（ItemEvent事件）
{
if（event.getStateChange（）==ItemEvent.SELECTED）
pictureLabel.setIcon（肖像[choiceBox.getSelectedIndex（）]）；
}
}
);
添加（图片标签）；
添加（即时标签）；
添加（选择框）；
}
}

---

TLDR：这是正确记录的吗？

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

• 软件类型（应用程序、库等）
• 文档的目标群体（程序员同事、最终用户等）
• 组织/公司的惯例和品味
• 等等

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

• 必须记录从包外部可见的所有类、字段和方法。这包括公共类以及公共和受保护的成员（字段和方法）。在您的情况下，缺少公共类的文档

• 私人物品和包装私人物品是否也必须记录取决于当地习俗。记录某事从来都不是错误的

• 方法的有用Javadoc文档描述了方法的功能。它还可以描述该方法是如何做到这一点的，但在大多数情况下，使用该方法的人并不真正感兴趣，也可以用非Javadoc注释来记录

• 文件应准确无误。如果存在前置条件，则应提及它们（例如，某些内容不能为

  null

  ，数字必须为

  =0

  ，等等）。如果有具体的角落案例，则应提及。如果一种方法有副作用，必须提到这一点

---

我希望这些建议能有所帮助。

这主要是基于观点的。。。每个组织都有自己的文档标准。。。例如，在一些情况下需要写作者，但在其他情况下被认为是不必要的/不相关的/不好的…哦，我明白了。非常感谢。我认为这是一种遵循某些被广泛排除的惯例的事情。oracle的文章可能会有帮助。如果你想问这个问题（而且主要是基于观点的），那么代码审查网站可能会是一个更好的匹配