О ясности и ясности - PullRequest
Новая
       32

О ясности и ясности

0 голосов
/ 08 июня 2011

Мнения разделились по этому вопросу ...

Ребята, скажите, у вас есть метод, определенный как 

public static String getTestName(JsonElement e) throws ParserException;

Как разработчик, который хочет делать правильные вещи, я хотел бы документировать это соответствующим образом. Оригинальная мысль была сказать:

«Возвращает строковое представление имени теста»

"Или действительно? Он возвращает строку? Я вижу это по сигнатуре метода, знаете ли. Не нужно повторять это, просто скажите:

«Возвращает название теста»

Так, кто это? Есть ли какое-либо значение в добавлении «Строковое представление ..» Это добавляет ясности или шума?

Я сообщаю, что вы решили.

Спасибо

1 Ответ

2 голосов
/ 08 июня 2011

Я бы положил туда "Струну" для ясности. На самом деле, я хотел бы сделать формулировку более похожей на «читабельную человеком строку» (если она предназначена для чтения человеком) или иным образом описать форматирование строки, если она предназначена для анализа или интерпретации другим программным обеспечением.

Лучший способ - подумать о следующем разработчике, который будет использовать этот API или работать над этим кодом. Для пользователей API они должны иметь возможность получать всю необходимую им информацию, не глядя на код. Разработчики должны уметь читать документацию (как в коде, так и в сгенерированной и другой внешней документации) и хорошо разбираться в системе. Достигните обеих этих целей соответствующим образом.

...