GhostDoc говорит самые ужасные вещи


От редакции. Первоначально я написал этот пост для блога SubMain. Вы можете проверить оригинал здесь, на их сайте, Пока ты там, взгляните на GhostDoc, который может помочь как с поддержкой комментариев кода, так и с генерацией справочной документации.

Несколько лет назад я работал для того или иного клиента. Честно говоря, у меня нет воспоминаний о специфике, за исключением предпочтения исчерпывающего комментирования. Каждый класс, каждый метод, каждое свойство и каждое поле.

Конечно, сначала я этого не узнал. Я даже не научился этому в разумные сроки. Вместо этого я узнал это близко ко времени передачи. И так все стало немного отчаянным.

Войдите в Ghostdoc, Мое Спасение

Теперь, в зависимости от вашей точки зрения, вы можете ругать меня за то, что я не старательно комментирую все это время. Я предложу объяснение, что в коде не было общедоступного компонента и никаких намеченных API или расширений. Также не требуются объяснения типа «почему»; это было просто.

Клиент процитировал политику. «Мы комментируем все, и мы берем этот код, поэтому мы хотим, чтобы вы делали то же самое». Оки Доки.

Теперь я знал, что в мире генерации кода и шаблонов T4 кто-то должен изобрели инструмент, который будет генерировать какие-то комментарии или другой. В то время быстрый поиск в Google привел меня к экономии: бесплатному инструменту GhostDoc.

Хотя это и не позволяло мне коврово бомбить мой код с комментариями в один клик (и это понятно), оно позволяло мне делать это одновременно для целых файлов. Достаточно хорошо. Я заплатил свое некомментированное покаяние, потратив примерно час комментирования таким образом.

А вы знаете, что? Это вызвало довольно респектабельные комментарии. Я помню впечатления, потому что ожидал пустых комментариев к шаблону. Вместо этого GhostDoc выяснил, как связать воедино некоторые глаголы и существительные.

Но это не все розы

Позвольте мне получить конкретную информацию о возможностях и ограничениях. Если бы я попытался сгенерировать документацию для мои шахматные кодовые базы TDDМетод «MovePiece», GhostDoc отнес бы меня к этому комментарию.

/// 
/// Moves the piece.
/// 
/// The origin.
/// The destination.
public void MovePiece(BoardCoordinate origin, BoardCoordinate destination)
{
    VerifyCoordinatesOrThrow(origin, destination);

    var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination);
    RemovePiece(origin);
    pieceToMove.HasMoved = true;

    ReconcileEnPassant(origin, destination, pieceToMove);
}

Видишь, о чем я? Я проделал довольно хорошую работу с четкими именами в этом методе, и GhostDoc наградил меня заголовком метода, который стоит сам по себе. MovePiece () перемещает кусок. В частности, он перемещает источник в пункт назначения. Не слишком потрепанный!

Но как насчет менее интуитивных структур имен? Ну, иногда все может стать странным.

Посмотреть изображение в Twitter

Да все верно. Вездесущий «основной» метод для приложения на C # «поддерживает аргументы».

Что-то еще?

Хорошо, это должно вызвать смешок. Но теперь, когда вы видите проблему, вы, вероятно, можете начать воображать всевозможные способы сбить с толку плохой инструмент (помимо этого, вы, вероятно, можете также понять, почему они хотят заставить вас уделять больше внимания сгенерированным комментариям, чем просто сказать «Генерировать комментарии для всего решения».)

Как вы думаете, что происходило тогда для неоперативного метода, который вы назвали «DoNothing?», Вы получите «Do the Nothing». Хорошая работа с сопряжением, но при этом пропущено намерение. Как насчет обработчика событий с именем «AfterInsert»? Это верно. «После вставки». И «TaskComplete»? «Задачи завершены». Теперь вот более сложный вопрос: «OnClose». Вы, вероятно, не ожидали «Oncloses the instance».

Конечно, другие проблемы идиоматического программирования также приводили в замешательство инструмент.

  • ToModel () -> «Пальцы модели».
  • ToTitleCase () -> «Обращается к регистру заголовков».
  • ToComment () -> «Автоматизирует комментарий»
  • ForgetPassword () -> «Забывает пароль»
  • SignOut () -> «Подписывает»

Исторически, вы могли заставить GhostDoc генерировать довольно забавные комментарии. Это означает, что если вы просто сгенерировали комментарии и больше не обращали внимания, вы можете выглядеть довольно абсурдно для кого-то, кто проверяет историю коммитов. К счастью, мой контроль за созданными комментариями спас меня от этой судьбы.

Смеяться над инструментом?

Так что стоит смеяться над GhostDoc. Хорошо обязательно. Эти комментарии забавны, и у каждого должно быть чувство юмора.

Но на более глубоком уровне, нет, не совсем. Обработка естественного языка представляет собой сложную проблему. Представьте, что вы пишете код для обработки имен классов, методов и переменных. Сначала вы можете подумать, что это легко. Но затем вы сталкиваетесь с такими вещами, как «ToString ()» и «TaskComplete ()». Как человек и программист, вы понимаете эти нюансы. Но как заставить свой код делать то же самое?

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

Что ты можешь сделать

Что вы должны делать, как пользователь GhostDoc? Ну, во-первых, не просто бездумно генерировать комментарии. Как минимум, делай то, что сделал я. Бездумно генерируйте комментарии, но также постарайтесь убедиться, что они имеют смысл, исправляя любые, которые не имеют.

Но, кроме того, используйте GhostDoc в качестве отправной точки для осмысленного общения. Создавайте XML-комментарии к документу только тогда, когда вы общаетесь с кем-либо, с помощью комментариев кода или IntelliSense / справочной документации. И когда вы это сделаете, поймите, что GhostDoc просто предлагает вам разумную отправную точку. Инструмент не претендует на то, чтобы заменить вас как программиста или коммуникатора ваших намерений. Это только начало.

Улучшение ситуации

Конечно, GhostDoc улучшился за эти годы. Например, если я напишу метод ToString () и сгенерирую, он больше не будет предлагать мне «toes the string». Вместо этого он делает это.

/// 
/// Returns a  that represents this instance.
/// 
/// A  that represents this instance.
public string ToString()
{
    return "I'm a board.";
}

Теперь GhostDoc на самом деле делает что-то довольно сложное. Он выясняет, что ToString () занимает особое место в языке и соответствующим образом адаптируется, объясняя это место размеченным комментарием.

Точно так же, если вы попытаетесь воспроизвести некоторые из махинаций, которые я описал выше, вы получите менее тупые результаты. Люди, работающие над базой кода GhostDoc, постоянно стремятся улучшить качество сгенерированных комментариев, даже если они служат только отправной точкой. Но они всегда могут воспользоваться некоторой помощью, поэтому я предлагаю следующее.

Напишите или прокомментируйте забавные или странные вещи, которые вы можете получить в GhostDoc при создании документации. Шутки в сторону. Это рассмешит вас, меня, читателей и авторов инструментов. Но это также привлечет внимание к недостаткам, что позволит им исправить, исправить и улучшить. Так что давай. Какие твои любимые шаровары GhostDoc?

Пожалуйста, обязательно скачать последнюю версию GhostDoc так что вам не нужно иметь дело с сгенерированными комментариями, цитируемыми в этом посте.