Java 正确的代码注释礼仪？
因此，在代码中注释函数似乎是语言中的一个常见主题，然而，对代码进行注释的正确方式是什么？我有一些示例代码，其中充斥着静态滥用和设计拙劣的机制，对Java来说仍然是新鲜事，并附有一些注释。注：这是我交的一个黑杰克项目，所以它最初是一个学校项目Java 正确的代码注释礼仪？,java,comments,Java,Comments,因此，在代码中注释函数似乎是语言中的一个常见主题，然而，对代码进行注释的正确方式是什么？我有一些示例代码，其中充斥着静态滥用和设计拙劣的机制，对Java来说仍然是新鲜事，并附有一些注释。注：这是我交的一个黑杰克项目，所以它最初是一个学校项目 import javafx.application.Application; import javafx.geometry.Pos; import javafx.scene.Scene; import javafx.scene.control.Button;
import javafx.application.Application;
import javafx.geometry.Pos;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.layout.HBox;
import javafx.scene.layout.Region;
import javafx.scene.layout.VBox;
import javafx.scene.paint.Color;
import javafx.stage.Stage;
import java.awt.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.ThreadLocalRandom;
public class Main extends Application {
//Screen dimensions
private static int width;
private static int height;
private static int value;
//Make new card regions
private static Region userZERO;
private static Region userONE;
private static Region userTWO;
private static Region userTHREE;
private static Region userFOUR;
private static Region dealerZERO;
private static Region dealerONE;
private static Region dealerTWO;
private static Region dealerTHREE;
private static Region dealerFOUR;
//Scene components
private static Button hitButton;
private static Button endButton;
private static Button resetButton;
private static VBox root;
private static HBox userCardHolder;
private static HBox buttonContainer;
private static HBox dealerCardHolder;
private static Label text;
private static Scene scene;
//Card values
private static ArrayList<Card> user = new ArrayList<>();
private static ArrayList<Card> dealer = new ArrayList<>();
private static ArrayList<Card> cards = new ArrayList<>();
private static boolean dealerBusted = false;
//Miscellaneous variable assignments
/* Constant random variables using
* ThreadLocalRandom, speeds up to x3
* faster than Java.util.Random, and is
* unique to this thread.
*/
private static final ThreadLocalRandom RANDOM = ThreadLocalRandom.current();
/* Main is first method called upon
* start, which uses the singular
* method, launch, to use the Start
* method which passes a Stage reference
* to begin building the Window.
*/
public static void main(String[] args) {
launch(args);
}
@Override
public void start(Stage stage) throws Exception {
width = ((int) Toolkit.getDefaultToolkit().getScreenSize().getWidth());
height = ((int) Toolkit.getDefaultToolkit().getScreenSize().getHeight());
cards = new ArrayList<>(Arrays.asList(Card.values()));
/* Creates rectangular regions for each card
* that will be represented in the GUI. Size
* is dictated by screen width and height,
* and in the shape of a rectangle to adapt
* to the shape of a playing card. Will set
* the preferential size, however has
* possibility of error if application is
* minimized.
*/
userZERO = new Region(); userZERO.setPrefSize(width / 12, height / 4.5);
userONE = new Region(); userONE.setPrefSize(width / 12, height / 4.5);
userTWO = new Region(); userTWO.setPrefSize(width / 12, height / 4.5);
userTHREE = new Region(); userTHREE.setPrefSize(width / 12, height / 4.5);
userFOUR = new Region(); userFOUR.setPrefSize(width / 12, height / 4.5);
dealerZERO = new Region(); dealerZERO.setPrefSize(width / 12, height / 4.5);
dealerONE = new Region(); dealerONE.setPrefSize(width / 12, height / 4.5);
dealerTWO = new Region(); dealerTWO.setPrefSize(width / 12, height / 4.5);
dealerTHREE = new Region(); dealerTHREE.setPrefSize(width / 12, height / 4.5);
dealerFOUR = new Region(); dealerFOUR.setPrefSize(width / 12, height / 4.5);
/* Sets the .css limitations of the regions.
* First, sets up image as the BACK.png image
* in the resources folder. Then edits
* background size to auto cover the entire
* region to prevent inappropriately sized
* images per region.
*/
userZERO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userONE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userTWO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userTHREE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userFOUR.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerZERO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerONE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerTWO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerTHREE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerFOUR.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
/* Setting up scene / Window information,
* and root information. Adding sub-roots
* to main-root for customized grid-pattern
* to contain cards on two rows, and a row
* of buttons in the middle independent
* of the card rows.
*/
root = new VBox(height / 25);
root.setPrefSize(width, height);
root.setMaxSize(width, height);
root.setMinSize(width, height);
root.alignmentProperty().setValue(Pos.CENTER);
root.setStyle(" -fx-background-image: url(\"images/BACKGROUND.png\"); -fx-background-size: cover, auto;");
text = new Label();
text.setPrefSize(width / 2, height / 20);
text.setStyle(" -fx-text-alignment: center; -fx-font: 48 arial;");
text.alignmentProperty().setValue(Pos.CENTER);
text.setTextFill(Color.RED.darker());
hitButton = new Button("HIT");
endButton = new Button("END");
resetButton = new Button("RESET");
userCardHolder = new HBox(width / 12);
userCardHolder.getChildren().addAll(userZERO, userONE, userTWO, userTHREE, userFOUR);
userCardHolder.alignmentProperty().setValue(Pos.CENTER);
buttonContainer = new HBox(width / 10);
buttonContainer.getChildren().addAll(hitButton, resetButton, endButton);
buttonContainer.alignmentProperty().setValue(Pos.CENTER);
dealerCardHolder = new HBox(width / 20);
dealerCardHolder.getChildren().addAll(dealerZERO, dealerONE, dealerTWO, dealerTHREE, dealerFOUR);
dealerCardHolder.alignmentProperty().setValue(Pos.CENTER);
root.getChildren().add(userCardHolder);
root.getChildren().add(text);
root.getChildren().add(buttonContainer);
root.getChildren().add(dealerCardHolder);
scene = new Scene(root);
stage = new Stage();
stage.setScene(scene);
stage.show();
hitButton.setPrefSize(width / 4.5, height / 12);
endButton.setPrefSize(width / 4.5, height / 12);
resetButton.setPrefSize(width / 4.5, height / 12);
user.clear();
dealer.clear();
buttonHandlers();
begin();
}
public static void buttonHandlers() {
/* Stop!
* Lambda Time!
*/
hitButton.setOnAction(e -> {
if (user.size() < 5) {
Card card = cards.get(RANDOM.nextInt(cards.size()));
user.add(card);
cards.remove(card);
switch (user.size()) {
case 3:
userTWO.setStyle(" -fx-background-image: url(\"images/" + user.get(user.size() - 1).toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 4:
userTHREE.setStyle(" -fx-background-image: url(\"images/" + user.get(user.size() - 1).toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 5:
userFOUR.setStyle(" -fx-background-image: url(\"images/" + user.get(user.size() - 1).toString() + ".png\"); -fx-background-size: cover, auto;");
break;
}
}
});
endButton.setOnAction(e -> {
for (Card c : dealer) {
switch (dealer.indexOf(c)) {
case 0:
dealerZERO.setStyle(" -fx-background-image: url(\"images/" + c.toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 1:
dealerONE.setStyle(" -fx-background-image: url(\"images/" + c.toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 2:
dealerTWO.setStyle(" -fx-background-image: url(\"images/" + c.toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 3:
dealerTHREE.setStyle(" -fx-background-image: url(\"images/" + c.toString() + ".png\"); -fx-background-size: cover, auto;");
break;
case 4:
dealerFOUR.setStyle(" -fx-background-image: url(\"images/" + c.toString() + ".png\"); -fx-background-size: cover, auto;");
break;
}
}
/* Checking scenarios for valid ending:
*
* Checks if one or both entites busted, and decided winner based
* on card amount and card value. House wins by default if same
* card values and card amount.
*/
if (checkForBust(user) && checkForBust(dealer)) {
System.out.println("BOTH BUSTED!");
text.setText("BOTH BUSTED!");
}
else if (checkForBust(user) && !checkForBust(dealer)) {
System.out.println("YOU BUSTED!");
text.setText("DEALER WON!");
}
else if (!checkForBust(user) && checkForBust(dealer)) {
System.out.println("DEALER BUSTED!");
text.setText("YOU WON!");
}
else if (getValue(user) > getValue(dealer)) {
System.out.println("USER WINS");
text.setText("YOU WON!");
}
else if ((getValue(user) == getValue(dealer)) && (user.size() >= dealer.size())) {
System.out.println("DEALER WINS");
text.setText("DEALER WON!");
}
else if ((getValue(user) == getValue(dealer)) && (user.size() <= dealer.size())) {
System.out.println("USER WINS");
text.setText("USER WON!");
}
else if ((getValue(user) == getValue(dealer)) && (user.size() == dealer.size())) {
System.out.println("DEALER WINS");
text.setText("DEALER WON!");
}
else if (getValue(dealer) > getValue(user)) {
System.out.println("DEALER WINS");
text.setText("DEALER WON!");
}
else {
System.out.println("ERROR!");
text.setText("ERROR GETTING WINNER!");
}
});
resetButton.setOnAction(e ->{
begin();
});
}
public static boolean checkForBust(List<Card> lc) {
value = 0;
for (Card c : lc) {
value += c.getValue();
}
if (lc.contains(Card.ACE_OF_CLUBS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_DIAMONDS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_HEARTS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_SPADES) && value > 21) { value -= 10; }
return value > 21;
}
public static int getValue(List<Card> lc) {
value = 0;
for (Card c : lc) {
value += c.getValue();
}
if (lc.contains(Card.ACE_OF_CLUBS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_DIAMONDS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_HEARTS) && value > 21) { value -= 10; }
if (lc.contains(Card.ACE_OF_SPADES) && value > 21) { value -= 10; }
return value;
}
public static void begin() {
text.setText("");
cards.clear();
user.clear();
dealer.clear();
cards = new ArrayList<>(Arrays.asList(Card.values()));
userZERO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userONE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userTWO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userTHREE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
userFOUR.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerZERO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerONE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerTWO.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerTHREE.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
dealerFOUR.setStyle(" -fx-background-image: url(\"images/BACK.png\"); -fx-background-size: cover, auto;");
Card card = cards.get(RANDOM.nextInt(cards.size()));
user.add(card);
cards.remove(card);
card = cards.get(RANDOM.nextInt(cards.size()));
user.add(card);
cards.remove(card);
userZERO.setStyle(" -fx-background-image: url(\"images/" + user.get(0) + ".png\"); -fx-background-size: cover, auto;");
userONE.setStyle(" -fx-background-image: url(\"images/" + user.get(1) + ".png\"); -fx-background-size: cover, auto;");
card = cards.get(RANDOM.nextInt(cards.size()));
dealer.add(card);
cards.remove(card);
card = cards.get(RANDOM.nextInt(cards.size()));
dealer.add(card);
cards.remove(card);
dealerZERO.setStyle(" -fx-background-image: url(\"images/" + dealer.get(0) + ".png\"); -fx-background-size: cover, auto;");
while(getValue(dealer) < 16 && dealer.size() < 5) {
card = cards.get(RANDOM.nextInt(cards.size()));
dealer.add(card);
cards.remove(card);
}
}
/* Switch to enum values:
* Card values and suits. Nested enum classes in a main class.
*/
public enum Card {
ACE_OF_SPADES(11, Suit.SPADES),
ACE_OF_HEARTS(11, Suit.HEARTS),
ACE_OF_DIAMONDS(11, Suit.DIAMONDS),
ACE_OF_CLUBS(11, Suit.CLUBS),
TWO_OF_SPADES(2, Suit.SPADES),
TWO_OF_HEARTS(2, Suit.HEARTS),
TWO_OF_DIAMONDS(2, Suit.DIAMONDS),
TWO_OF_CLUBS(2, Suit.CLUBS),
THREE_OF_SPADES(3, Suit.SPADES),
THREE_OF_HEARTS(3, Suit.HEARTS),
THREE_OF_DIAMONDS(3, Suit.DIAMONDS),
THREE_OF_CLUBS(3, Suit.CLUBS),
FOUR_OF_SPADES(4, Suit.SPADES),
FOUR_OF_HEARTS(4, Suit.HEARTS),
FOUR_OF_DIAMONDS(4, Suit.DIAMONDS),
FOUR_OF_CLUBS(4, Suit.CLUBS),
FIVE_OF_SPADES(5, Suit.SPADES),
FIVE_OF_HEARTS(5, Suit.HEARTS),
FIVE_OF_DIAMONDS(5, Suit.DIAMONDS),
FIVE_OF_CLUBS(5, Suit.CLUBS),
SIX_OF_SPADES(6, Suit.SPADES),
SIX_OF_HEARTS(6, Suit.HEARTS),
SIX_OF_DIAMONDS(6, Suit.DIAMONDS),
SIX_OF_CLUBS(6, Suit.CLUBS),
SEVEN_OF_SPADES(7, Suit.SPADES),
SEVEN_OF_HEARTS(7, Suit.HEARTS),
SEVEN_OF_DIAMONDS(7, Suit.DIAMONDS),
SEVEN_OF_CLUBS(7, Suit.CLUBS),
EIGHT_OF_SPADES(8, Suit.SPADES),
EIGHT_OF_HEARTS(8, Suit.HEARTS),
EIGHT_OF_DIAMONDS(8, Suit.DIAMONDS),
EIGHT_OF_CLUBS(8, Suit.CLUBS),
NINE_OF_SPADES(9, Suit.SPADES),
NINE_OF_HEARTS(9, Suit.HEARTS),
NINE_OF_DIAMONDS(9, Suit.DIAMONDS),
NINE_OF_CLUBS(9, Suit.CLUBS),
TEN_OF_SPADES(10, Suit.SPADES),
TEN_OF_HEARTS(10, Suit.HEARTS),
TEN_OF_DIAMONDS(10, Suit.DIAMONDS),
TEN_OF_CLUBS(10, Suit.CLUBS),
JACK_OF_SPADES(10, Suit.SPADES),
JACK_OF_HEARTS(10, Suit.HEARTS),
JACK_OF_DIAMONDS(10, Suit.DIAMONDS),
JACK_OF_CLUBS(10, Suit.CLUBS),
QUEEN_OF_SPADES(10, Suit.SPADES),
QUEEN_OF_HEARTS(10, Suit.HEARTS),
QUEEN_OF_DIAMONDS(10, Suit.DIAMONDS),
QUEEN_OF_CLUBS(10, Suit.CLUBS),
KING_OF_SPADES(10, Suit.SPADES),
KING_OF_HEARTS(10, Suit.HEARTS),
KING_OF_DIAMONDS(10, Suit.DIAMONDS),
KING_OF_CLUBS(10, Suit.CLUBS);
private int value;
private Suit suit;
Card(int value, Suit suit) {
this.value = value;
this.suit = suit;
}
public int getValue() { return value; }
}
public enum Suit {
HEARTS(),
DIAMONDS(),
CLUBS(),
SPADES();
Suit(){}
}
}
回到JavaDocs，这对学校的项目来说是理想的吗？从某种意义上说，它让项目看起来“专业”吗？用Java和英语编写的代码是专业的还是有损于专业性。还有，我应该描述一下它们是什么吗？他们都做什么，等等？很明显，我不希望99%的代码都是注释，但我确实希望有一些注释，没有你们在书中看到的填充类型的内容。是什么因素让信息被理想地广泛接受并写在评论中？当我们被迫使用评论时，会强烈地感觉到有什么地方出错了。除了在javadocs中，当我们真的需要注释代码时，可能代码编写得不太好，甚至不能正确地表示业务规则 例如：这里有注释//屏幕尺寸。为什么不创建具有这些属性的对象
我喜欢它，因为它解释了很多难闻的气味、代码模式、重构策略等等。此外，它还提供了一些关于何时以及如何评论的提示。关于评论有几种不同的观点。一些开发人员认为注释是对糟糕代码的道歉，但我不同意这种观点，认为它们很有用。阅读文章的一种替代方法是分析用Java编写的流行开源项目的源代码，并尝试模仿它们的风格。流行的JavaIDE，如NetBeans、Eclipse和IntelliJ，都是用Java编写的开源项目，因此它们是很好的起点 Netbeans： 日食： IntelliJ：
您不必理解逻辑，只需记录作者对代码的注释。过一段时间后，您应该开始看到一些非常相似的地方，继续并将它们吸收到您的编码曲目中 你读了吗？与你的问题无关，但我想说你的方法做得太多了。它们应该只做一件事，并且应该适合你的屏幕。开始是做太多的事情，考虑把多个方法分成真的依赖于组织，如果你能养成使用java doc风格评论的习惯，我会做的。看看像谷歌这样备受推崇的公司的编码标准。@可怕的袋熊总的来说，其中一些术语对我来说有点太混乱了，我还没有达到可以轻松阅读的程度，但我仍然能理解其中的一部分。然而，我在这方面的水平还不够高，无论是英语还是编码术语，Javadocs都很棒，它可以让其他开发人员知道你的方法和字段在做什么。我会在Javadoc中写一个方法如何在黑盒级别工作/行为，如果我在实际实现中使用了任何复杂的东西，我会适当地添加注释。我第一次看到这个网站，非常准确和有用的内容。谢谢分享！不客气。一般来说，他们提供的课程也是基础的，但非常好。
/* store some comments
* around here
*/