Comment on code, Race program

Question

Hello! Please tell me how to correctly describe a comment to the race code with an example!

Thanks in advance!

package dragracing; /* Методы интерфейса CarInterface */ public interface CarInterface { public int getId(); public void setId(int id); public String getDriver(); public void setDriver(String driver); public String getManufacturer(); public void setManufacturer(String manufacturer); public int getMaxSpeed(); public void setMaxSpeed(int maxSpeed); public String getModel(); public void setModel(String model); public int getVelocity(); public void setVelocity(int velocity); public long getCurrentSpeed(); public void setCurrentSpeed(long currentSpeed); public long getRunDistance(); public void setRunDistance(long runDistance); public int getRunTime(); public void setRunTime(int runTime); } /* Поля класса Car интерфейса CarInterface */ class Car implements CarInterface { private int id; private String manufacturer; private String model; private int velocity; private int maxSpeed; private long currentSpeed = 0; private long runDistance = 0; private int runTime = 0; private String driver; /* Конструктор класса Car с входными параметрами элемента класса Car */ public Car(Car car) { this.id = car.id; this.manufacturer = car.manufacturer; this.model = car.model; this.velocity = car.velocity; this.maxSpeed = car.maxSpeed; this.driver = car.driver; this.currentSpeed = 0; this.runDistance = 0; this.runTime = 0; } /* Конструктор класса Car с входными параметрами */ public Car(int id, String manufacturer, String model, int velocity, int maxSpeed, String driver) { this.id = id; this.manufacturer = manufacturer; this.model = model; this.velocity = velocity; this.maxSpeed = maxSpeed; this.driver = driver; } /* Метод getId возращающий значения id */ public int getId() { return this.id; } /* Метод setId невозращающий значения id */ public void setId(int id) { this.id = id; } /* Метод getDriver возращающий значения driver */ public String getDriver() { return this.driver; } /* Метод setDriver невозращающий значения driver */ public void setDriver(String driver) { this.driver = driver; } /* Метод getManufacturer возращающий значения manufacturer */ public String getManufacturer() { return this.manufacturer; } /* Метод setManufacturer невозращающий значения manufacturer */ public void setManufacturer(String manufacturer) { this.manufacturer = manufacturer; } /* Метод getMaxSpeed возращающий значения maxSpeed */ public int getMaxSpeed() { return this.maxSpeed; } /* Метод setMaxSpeed невозращающий значения maxSpeed */ public void setMaxSpeed(int maxSpeed) { this.maxSpeed = maxSpeed; } /* Метод getModel возращающий значения model */ public String getModel() { return this.model; } /* Метод setModel невозращающий значения model */ public void setModel(String model) { this.model = model; } /* Метод getVelocity возращающий значения velocity */ public int getVelocity() { return this.velocity; } /* Метод setVelocity невозращающий значения velocity */ public void setVelocity(int velocity) { this.velocity = velocity; } /* Метод getCurrentSpeed возращающий значения currentSpeed */ public long getCurrentSpeed() { return this.currentSpeed; } /* Метод setCurrentSpeed невозращающий значения currentSpeed */ public void setCurrentSpeed(long currentSpeed) { this.currentSpeed = currentSpeed; } /* Метод getRunDistance возращающий значения runDistance */ public long getRunDistance() { return this.runDistance; } /* Метод setRunDistance невозращающий значения runDistance */ public void setRunDistance(long runDistance) { this.runDistance = runDistance; } /* Метод getRunTime возращающий значения runTime */ public int getRunTime() { return this.runTime; } /* Метод setRunTime невозращающий значения runTime */ public void setRunTime(int runTime) { this.runTime = runTime; } }

Second class

 package dragracing; /* импорт библиотек */ import java.util.HashMap; import java.util.Map; /* Поля класса Dragracing с типизированными списакми */ public class Dragracing { private static Map<Integer, Car> cars = new HashMap<Integer, Car>(); /* Статическая константа trackLength */ private static final int trackLength = 402; /* Статическая метод setCars невозращающий не какого значения с описанием значений и названий */ private static void setCars() { cars.put(1, new Car(1, "Toyota", "Celica", 6, 250, "Alex")); cars.put(2, new Car(2, "Dodge", "Viper", 7, 310, "Steve")); cars.put(3, new Car(3, "Porsche", "911", 9, 320, "Martin")); cars.put(4, new Car(4, "Dodge", "Challenger", 9, 250, "Andrew")); cars.put(5, new Car(5, "Toyota", "MR2", 5, 250, "Jim")); cars.put(6, new Car(6, "Honda", "NSX", 8, 280, "Hiroki")); cars.put(7, new Car(7, "Chevrolet", "Camaro", 8, 270, "Ricky")); cars.put(8, new Car(8, "Nissan", "GTR", 8, 310, "Kito")); cars.put(9, new Car(9, "Lamborghini", "Countach", 8, 300, "Linda")); cars.put(10, new Car(10, "VAZ", "2107", 8, 200, "Vasiliy")); } /* Статическая метод refresh невозращающий не какого значения с входными параметрами с условным оператором if */ private static void refresh(Car car, int time) { long maxSpeed = Math.round(car.getMaxSpeed()/3.6); long curSpeed = Math.round(car.getVelocity() * time); if(curSpeed > maxSpeed) curSpeed = maxSpeed; car.setRunDistance(car.getRunDistance() + curSpeed > trackLength ? trackLength : car.getRunDistance() + curSpeed); car.setCurrentSpeed(Math.round(curSpeed*3.6)); } /* Статическая метод main невозращающий не какого значения с входными параметрами с исключительной ситуацией throws InterruptedException так же с типизированным списком с циклом for переменной boolean с циклом while c условным оператором if */ public static void main(String[] args) throws InterruptedException { HashMap<Integer, Car> results = new HashMap<Integer, Car>(); setCars(); int runNum = 1; for(int i = 1; i < cars.size(); i++) { Car left = new Car(cars.get(i++)); Car right = new Car(cars.get(i)); boolean run = true; System.out.println("Run " + runNum + ": " + left.getDriver() + " on " + left.getManufacturer() + " " + left.getModel() + " vs. " + right.getDriver() + " on " + right.getManufacturer() + " " + right.getModel()); Thread.sleep(3000); System.out.println("Ready!"); Thread.sleep(1000); System.out.println("Steady!"); Thread.sleep(1000); System.out.println("GO!"); int seconds = 0; while(run) { System.out.println("Run " + runNum + ": " + left.getDriver() + " on " + left.getManufacturer() + " " + left.getModel() + " vs. " + right.getDriver() + " on " + right.getManufacturer() + " " + right.getModel()); System.out.println(left.getDriver() + ": " + left.getRunDistance() + " meters, " + left.getCurrentSpeed() + " km/h"); System.out.println(right.getDriver() + ": " + right.getRunDistance() + " meters, " + right.getCurrentSpeed() + " km/h"); Thread.sleep(1000); seconds++; if(left.getRunTime() == 0) refresh(left, seconds); if(right.getRunTime() == 0) refresh(right, seconds); if(left.getRunTime() > 0 && right.getRunTime() > 0) run = false; if(left.getRunDistance() >= trackLength && left.getRunTime() == 0) { left.setRunTime(seconds); results.put(cars.size() - results.size(), left); } if(right.getRunDistance() >= trackLength && right.getRunTime() == 0) { right.setRunTime(seconds); results.put(cars.size() - results.size(), right); } } runNum++; } for(Map.Entry<Integer, Car> set : results.entrySet()) System.out.println(set.getValue().getRunTime() + " seconds: " + set.getValue().getDriver() + " on " + set.getValue().getManufacturer() + " " + set.getValue().getModel()); } }

Accepted Answer · 2011-11-29T06:47:35

Correct - this is done using JavaDoc markup)

Describe the purpose of the class and all public methods, their parameters and return values.

SetMaxSpeed method non-return maxSpeed values

This is not entirely correct. The fact that this is a method called setMaxSpeed , we setMaxSpeed see. But what maxSpeed is, nobody knows (as well as the wording "non-return value"). It would be better to have something like:

 /** * Устанавливает значение максимальной скорости. */

And for getMaxSpeed respectively:

 /** * Возвращает значение максимальной скорости. * @return Максимальная скорость, если она задана, в противном случае -1 */

(There are no such restrictions in your code, I added for clarity)

The main method to document again makes no sense. All programmers are so well aware that this is the entry point to the program.

Static method refresh not returning no value with input parameters with if statement

Also not very useful wording. The fact that this static method can be seen as well, and the fact that it has a conditional operator inside, should not worry us at all (imagine that the method is a black box). It would be more useful to describe the general principle of work in a difficult case. And, of course, the description of the car and time parameters is extremely lacking. What kind of car is it, what time do you need to pass? javadoc should briefly answer these questions. That is, in fact, a programmer who will use this code (for example, in six months) will want to read something in the spirit of:

 /** * Обновляет состояние машины на указанный временной интервал. * * При расчете учитывается длина трассы и максимальная скорость. * @param car Обновляемая машина * @param time Временной интервал относительно предыдущего состояния */

The main thing: comments must carry really useful information.

Answer 2 · 2011-11-29T19:30:31

I fully agree with @Nofate , but I’ll add something from myself:

1) the names of the constants are always in upper case. due to the fact that with the help of the register of letters there is no possibility to separate the logical components of the name (compare: trackLength and TRACKLENGTH), the underscore is used in constants.

 private static final int trackLength = 402; // а еще я группы констант отделяю такими комментариями на логические группы // пример1: константы для автомобиля ... // пример2: константы для трассы private static final int TRACK_LENGTH = 402; // максимально-допустимая длина трека

^^ a small line will help a person figure out why this constant is needed

2) it so happened that all the methods with the 'set' prefix are used to set some properties of the object. it's not typical of java to use it for other methods. Yes, and no semantic load of his name now carries

 private static void setCars() {} // установить автомобили? private static void setUpCars() {} // настроить автомобили private static void initialize() // инициализация приложения (эта строчка должна быть в javadoc к методу) { // проинициализировать автомобили initDefaultCars(); // проинилиализировать что-то еще ... }

I consider the last option the most optimal. he gives the maximum amount of information

3) the main method looks terrible and completely unreadable. methods, in particular, overloaded with functionality should be divided into logical sections. add a comment for each and separate sections with a blank line.

 public class Dragracing { private static Map < Integer, Car > cars = new HashMap < Integer, Car > () ; private static final int TRACK_LENGTH = 402 ; public static void main ( final String[] args ) { // init application setCars () ; // обьявление переменных final HashMap < Integer, Car > results = new HashMap < Integer, Car > () ; // здесь храним результаты int runNum = 1 ; // номер заезда // считаем что-то там для всех машин for ( int i = 1 ; i < cars.size () ; i++ ) { // для теста используем две соседние? машины final Car right = new Car ( cars.get ( i ) ) ; final Car left = new Car ( cars.get ( i++ ) ) ; // выводим информацию о учасниках displayRaceStart ( runNum, left, right ) ; // подсчитываем результаты заезда int seconds = 0 ; boolean run = true ; while ( run ) { // выводим текущее состояние displayRaceStatus ( runNum, left, right ) ; // пишем для чего увиличивается счетчик seconds++ ; // обновляем состояние автомобилей updateState ( left, seconds ) ; updateState ( right, seconds ) ; // проверяем условие остановки соревнования? (заменить на нужное) if ( (left.getRunTime () > 0) && (right.getRunTime () > 0) ) { run = false ; } // обновляем результаты гонки updateRaceResult ( results, left, seconds ) ; updateRaceResult ( results, right, seconds ) ; } // увиличиваем счетчик кругов? заездов? runNum++ ; } // выводим результаты гонки (коммент излишний? а не факт что в реальной програме будет только 1 строчка после него) displayRaceResults ( results ) ; } private static void displayRaceResults ( final HashMap < Integer, Car > results ) { for ( final Map.Entry < Integer, Car > set : results.entrySet () ) { System.out.println ( set.getValue ().getRunTime () + " seconds: " + set.getValue ().getDriver () + " on " + set.getValue ().getManufacturer () + " " + set.getValue ().getModel () ) ; } } private static void displayRaceStart ( final int runNum, final Car a, final Car b ) { System.out.println ( "Run " + runNum + ": " + a.getDriver () + " on " + a.getManufacturer () + " " + a.getModel () + " vs. " + b.getDriver () + " on " + b.getManufacturer () + " " + b.getModel () ) ; pause ( 3000 ) ; System.out.println ( "Ready!" ) ; pause ( 1000 ) ; System.out.println ( "Steady!" ) ; pause ( 1000 ) ; System.out.println ( "GO!" ) ; } private static void displayRaceStatus ( final int runNum, final Car left, final Car right ) { System.out.println ( "Run " + runNum + ": " + left.getDriver () + " on " + left.getManufacturer () + " " + left.getModel () + " vs. " + right.getDriver () + " on " + right.getManufacturer () + " " + right.getModel () ) ; System.out.println ( left.getDriver () + ": " + left.getRunDistance () + " meters, " + left.getCurrentSpeed () + " km/h" ) ; System.out.println ( right.getDriver () + ": " + right.getRunDistance () + " meters, " + right.getCurrentSpeed () + " km/h" ) ; pause ( 1000 ) ; } private static void pause ( final long delay ) { try { Thread.sleep ( delay ) ; } catch ( final InterruptedException e ) { // failed sleep - ignore } } private static void refreshCarState ( final Car car, final int time ) { final long maxSpeed = Math.round ( car.getMaxSpeed () / 3.6 ) ; long curSpeed = Math.round ( car.getVelocity () * time ) ; if ( curSpeed > maxSpeed ) { curSpeed = maxSpeed ; } car.setRunDistance ( (car.getRunDistance () + curSpeed) > TRACK_LENGTH ? TRACK_LENGTH : car.getRunDistance () + curSpeed ) ; car.setCurrentSpeed ( Math.round ( curSpeed * 3.6 ) ) ; } private static void setCars () { cars.put ( 1, new Car ( 1, "Toyota", "Celica", 6, 250, "Alex" ) ) ; cars.put ( 2, new Car ( 2, "Dodge", "Viper", 7, 310, "Steve" ) ) ; cars.put ( 3, new Car ( 3, "Porsche", "911", 9, 320, "Martin" ) ) ; cars.put ( 4, new Car ( 4, "Dodge", "Challenger", 9, 250, "Andrew" ) ) ; cars.put ( 5, new Car ( 5, "Toyota", "MR2", 5, 250, "Jim" ) ) ; cars.put ( 6, new Car ( 6, "Honda", "NSX", 8, 280, "Hiroki" ) ) ; cars.put ( 7, new Car ( 7, "Chevrolet", "Camaro", 8, 270, "Ricky" ) ) ; cars.put ( 8, new Car ( 8, "Nissan", "GTR", 8, 310, "Kito" ) ) ; cars.put ( 9, new Car ( 9, "Lamborghini", "Countach", 8, 300, "Linda" ) ) ; cars.put ( 10, new Car ( 10, "VAZ", "2107", 8, 200, "Vasiliy" ) ) ; } private static void updateRaceResult ( final HashMap < Integer, Car > results, final Car car, final int seconds ) { // race results updates when car finishes if ( (TRACK_LENGTH <= car.getRunDistance ()) && (0 == car.getRunTime ()) ) { updateRaceResultImpl ( results, car, seconds ) ; } } private static void updateRaceResultImpl ( final HashMap < Integer, Car > results, final Car car, final int seconds ) { // update car state car.setRunTime ( seconds ) ; // update results results.put ( Integer.valueOf ( cars.size () - results.size () ), car ) ; } private static void updateState ( final Car left, final int seconds ) { if ( left.getRunTime () == 0 ) { refreshCarState ( left, seconds ) ; } } }

> it just so happens that all methods with the 'set' prefix are used for ... I will correct you a little here.
This is not just "established", but a very clear concept called JavaBeans, which provides for getters and setters for object properties.
I did not quite put it correctly, I meant that the limited use of methods with the prefix set in java is a consequence of the fact that you wrote.
After all, javabeans / pojo in no way imposes restrictions on the names of other methods (where "other" means any methods except getters / setters - get / set / is)

Comment on code, Race program

2 answers 2

More articles: