документация API и “пределы значения”: они соответствуют?
Обычно это код. Вот простой пример:
import java.util.*;
public class GarbageCollector {
public static void main(String... args) {
System.out.printf("Testing...%n");
List<Double> list = new ArrayList<Double>();
for (int outer = 0; outer < 10000; outer++) {
// list = new ArrayList<Double>(10000); // BAD
// list = new ArrayList<Double>(); // WORSE
list.clear(); // BETTER
for (int inner = 0; inner < 10000; inner++) {
list.add(Math.random());
}
if (outer % 1000 == 0) {
System.out.printf("Outer loop at %d%n", outer);
}
}
System.out.printf("Done.%n");
}
}
Использование java 1.6.0_24-b07 На 32-разрядной версии Windows 7.
java -Xloggc: gc.log GarbageCollector
Затем посмотрите на gc.log
- Запущено 444 раза с использованием метода BAD
- Запущено 666 раз с использованием метода WORSE
- Триггер 354 раза с использованием метода BETTER g2]
Теперь предоставлено, это не лучший тест или лучший дизайн, но когда вы столкнулись с ситуацией, когда у вас нет выбора, кроме как реализовать такой цикл или при работе с существующим кодом, который ведет себя плохо, выбирая повторное использование объектов вместо создания новых может уменьшить количество сборов сборщика мусора на пути ...
4 ответа
Я думаю, что они могут принадлежать вместе, но должны не обязательно принадлежать вместе. В Вашем сценарии кажется, что это имеет смысл, что пределы документируются таким способом, которым они появляются в сгенерированной документации API и intellisense (если язык/IDE поддерживает его).
Я думаю, что это действительно зависит от языка также. Например, у Ada есть собственный тип данных, который является "ограниченным целым числом", где Вы определяете целочисленную переменную и явно указываете, что это будет только (и всегда) быть в определенном числовом диапазоне. В этом случае сам тип данных указывает на ограничение. Это должно все еще быть видимым и поддающимся обнаружению через документацию API и intellisense, но не было бы чем-то, что разработчик должен указать в комментариях.
Однако языки как Java и C# не имеют этого типа ограниченного целого числа, таким образом, разработчик должен был бы указать его в комментариях, если бы это была информация, которая должна стать частью общедоступной документации.
Я думаю, что они делают и всегда помещали комментарии в заголовочные файлы (C++) arcordingly.
В дополнение к действительным входным/выводам/возвратам комментариям я также отмечаю, какими исключениями является likly, который будет брошен функцией (так как я часто хочу использовать возвращаемое значение для того, чтобы... хорошо возвратить значение, я предпочитаю исключения по кодам ошибок),
//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);
Я думаю, что те виды граничных условий совершенно определенно принадлежат API. Однако я был бы (и часто делайте), пойдите шаг вперед и укажите на то, ЧТО означают те нулевые значения. Или я указываю, что это выдаст исключение, или я объясняю, чем состоят в том ожидаемые результаты, когда граничное значение передается в.
Трудно не забыть всегда делать это, но это - хорошая вещь для пользователей Вашего класса. Также трудно поддержать его, если контракт изменения подарков метода (как нулевые значения изменяются на не быть позволенным)... необходимо быть прилежными также для обновления документов при изменении семантики метода.
Улан @Fire:Правильно! я забыл об исключении, но я хотел бы видеть их упомянутый, особенно исключение 'во время выполнения' непроверенное, которое мог выдать этот открытый метод
@Mike Stone:
необходимо быть прилежными также для обновления документов при изменении семантики метода.
Мммм я верная надежда, что общедоступная документация API по крайней мере обновляется каждый раз, когда изменение - который влияет на контракт функции - происходит. В противном случае те документации API могли быть отбрасыванием в целом.
Чтобы добавить еду к Вашему мысли (и пойти с @Scott Dorman), я просто натыкаюсь на будущее java7 аннотаций
Что делает, который означает? Тот определенные 'граничные условия', вместо того, чтобы находиться в документации, должны быть более обеспечены в самом API и автоматически используемые, во время компиляции, с соответствующим 'утверждают' сгенерированный код.
Тому пути, если '@CheckForNull' находится в API, устройстве записи функции, даже не могло бы сойти с рук документирование его! И если семантическое изменение, его API отразит что изменение (как 'больше @CheckForNull', например)
Такой подход предполагает, что документация, для 'граничных условий', является дополнительной премией, а не обязательной практикой.
Однако это не покрывает специальные значения эхо-сигнала функции. Для этого все еще необходима подробная документация.